Bump version to v20.0b0

Co-authored-by: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com>
Co-authored-by: Viicos <65306057+Viicos@users.noreply.github.com>
Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com>

.git-blame-ignore-revs

@@ -0,0 +1,7 @@
+# .git-blame-ignore-revs
+# Use locally as `git blame file.py --ignore-revs-file .git-blame-ignore-revs`
+# or configure git to always use it: `git config blame.ignoreRevsFile .git-blame-ignore-revs`
+# First migration to code style Black (#2122)
+264b2c9c72691c5937b80e84e061c52dd2d8861a
+# Use Black more extensively (#2972)
+950d9a0751d79b92d78ea44344ce3e3c5b3948f9

.github/CONTRIBUTING.rst

@@ -13,7 +13,7 @@ Setting things up
 
    .. code-block:: bash
 
-      $ git clone https://github.com/<your username>/python-telegram-bot --recursive
+      $ git clone https://github.com/<your username>/python-telegram-bot
       $ cd python-telegram-bot
 
 3. Add a track to the original repository:
@@ -26,7 +26,7 @@ Setting things up
 
    .. code-block:: bash
 
-      $ pip install -r requirements.txt -r requirements-dev.txt
+      $ pip install -r requirements-all.txt
 
 
 5. Install pre-commit hooks:
@@ -82,7 +82,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 the `Black`_ coder 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 `Black`_ for code formatting. Plugins for Black exist for some `popular editors`_. You can use those instead of manually formatting everything.
 
    - Please ensure that the code you write is well-tested.
 
@@ -98,6 +98,13 @@ Here's how to make a one-off code change.
 
         $ pytest -v
 
+     Since the tests can take a while to run, you can speed things up by running them in parallel
+     using `pytest-xdist`_ (note that this may effect the result of the test in some rare cases):
+
+     .. code-block:: bash
+
+        $ pytest -v -n auto --dist=loadfile
+
      To run ``test_official`` (particularly useful if you made API changes), run
 
      .. code-block:: bash
@@ -263,19 +270,21 @@ break the API classes. For example:
         self.last_name = last_name
 
 
-.. _`Code of Conduct`: https://www.python.org/psf/codeofconduct/
+.. _`Code of Conduct`: https://www.python.org/psf/conduct/
 .. _`issue tracker`: https://github.com/python-telegram-bot/python-telegram-bot/issues
 .. _`Telegram group`: https://telegram.me/pythontelegrambotgroup
-.. _`PEP 8 Style Guide`: https://www.python.org/dev/peps/pep-0008/
-.. _`sphinx`: http://sphinx-doc.org
-.. _`Google Python Style Guide`: http://google.github.io/styleguide/pyguide.html
+.. _`PEP 8 Style Guide`: https://peps.python.org/pep-0008/
+.. _`sphinx`: https://www.sphinx-doc.org/en/master
+.. _`Google Python Style Guide`: https://google.github.io/styleguide/pyguide.html
 .. _`Google Python Style Docstrings`: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
-.. _AUTHORS.rst: ../AUTHORS.rst
+.. _AUTHORS.rst: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/AUTHORS.rst
 .. _`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/editor_integration.html
-.. _`RTD`: https://python-telegram-bot.readthedocs.io/
-.. _`RTD build`: https://python-telegram-bot.readthedocs.io/en/doc-fixes
+.. _`popular editors`: https://black.readthedocs.io/en/stable/integrations/editors.html
+.. _`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
 .. _`section`: #documenting
+.. _`pytest-xdist`: https://github.com/pytest-dev/pytest-xdist

.github/pull_request_template.md

@@ -15,14 +15,14 @@ Hey! You're PRing? Cool! Please have a look at the below checklist. It's here to
 
 * New classes:
     - [ ] Added `self._id_attrs` and corresponding documentation
-    - [ ] `__init__` accepts `**_kwargs`
-    
+    - [ ] `__init__` accepts `api_kwargs` as kw-only
+
 * Added new shortcuts:
     - [ ] In `Chat` & `User` for all methods that accept `chat/user_id`
     - [ ] In `Message` for all methods that accept `chat_id` and `message_id`
     - [ ] For new `Message` shortcuts: Added `quote` argument if methods accepts `reply_to_message_id`
     - [ ] In `CallbackQuery` for all methods that accept either `chat_id` and `message_id` or `inline_message_id`
-    
+
 * If relevant:
 
     - [ ] Added new constants at `telegram.constants` and shortcuts to them as class variables
@@ -32,6 +32,7 @@ Hey! You're PRing? Cool! Please have a look at the below checklist. It's here to
       - [ ] Add the handlers to the warning loop in the `ConversationHandler`
     - [ ] Added new filters for new message (sub)types
     - [ ] Added or updated documentation for the changed class(es) and/or method(s)
+    - [ ] Added the new method(s) to `_extbot.py`
     - [ ] Added or updated `bot_methods.rst`
-    - [ ] Updated the Bot API version number in all places: `README.rst` and `README_RAW.rst` (including the badge), as well as `telegram.constants.BOT_API_VERSION`
+    - [ ] Updated the Bot API version number in all places: `README.rst` and `README_RAW.rst` (including the badge), as well as `telegram.constants.BOT_API_VERSION_INFO`
     - [ ] Added logic for arbitrary callback data in `tg.ext.Bot` for new methods that either accept a `reply_markup` in some form or have a return type that is/contains `telegram.Message`

.github/stale.yml

@@ -1,14 +0,0 @@
-# Number of days of inactivity before an issue becomes stale
-daysUntilStale: 3
-# Number of days of inactivity before a stale issue is closed
-daysUntilClose: 2
-# Only issues or pull requests with all of these labels are check if stale. Defaults to `[]` (disabled)
-onlyLabels: question
-# Label to use when marking an issue as stale
-staleLabel: stale
-# Comment to post when marking as stale. Set to `false` to disable
-markComment: false
-# Comment to post when closing a stale issue. Set to `false` to disable
-closeComment: >
-  This issue has been automatically closed due to inactivity. Feel free to comment in order to reopen
-  or ask again in our Telegram support group at https://t.me/pythontelegrambotgroup.

.github/workflows/docs-linkcheck.yml

@@ -0,0 +1,27 @@
+name: Check Links in Documentation
+on:
+  schedule:
+    # First day of month at 05:46 in every 2nd month
+    - cron: '46 5 1 */2 *'
+
+jobs:
+  test-sphinx-build:
+    name: test-sphinx-linkcheck
+    runs-on: ${{matrix.os}}
+    strategy:
+      matrix:
+        python-version: [3.7]
+        os: [ubuntu-latest]
+      fail-fast: False
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        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-all.txt
+      - name: Check Links
+        run: sphinx-build docs/source docs/build/html -W --keep-going -j auto -b linkcheck

.github/workflows/docs.yml

@@ -3,12 +3,10 @@ on:
   pull_request:
     branches:
       - master
-      - v14
       - doc-fixes
   push:
     branches: 
       - master
-      - v14
       - doc-fixes
 
 jobs:
@@ -22,18 +20,13 @@ jobs:
       fail-fast: False
     steps:
       - uses: actions/checkout@v3
-      - name: Initialize vendored libs
-        run:
-          git submodule update --init --recursive
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
         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.txt
-          python -W ignore -m pip install -r requirements-dev.txt
-          python -W ignore -m pip install -r docs/requirements-docs.txt
+          python -W ignore -m pip install -r requirements-all.txt
       - name: Build docs
         run: sphinx-build docs/source docs/build/html -W --keep-going -j auto

.github/workflows/example_notifier.yml

@@ -1,16 +0,0 @@
-name: Warning maintainers
-on:
-  pull_request_target:
-    paths: examples/**
-permissions:
- pull-requests: write
-jobs:
-  job:
-    runs-on: ubuntu-latest
-    name: about example change
-    steps:
-      - name: running the check
-        uses: Poolitzer/notifier-action@master
-        with:
-          notify-message: Hey there. Relax, I am just a little warning for the maintainers to release directly after merging your PR, otherwise we have broken examples and people might get confused :)
-          repo-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/lock.yml

@@ -9,10 +9,10 @@ jobs:
   lock:
     runs-on: ubuntu-latest
     steps:
-      - uses: dessant/lock-threads@v2.0.1
+      - uses: dessant/lock-threads@v3.0.0
         with:
           github-token: ${{ github.token }}
-          issue-lock-inactive-days: '7'
+          issue-inactive-days: '7'
           issue-lock-reason: ''
-          pr-lock-inactive-days: '7'
+          pr-inactive-days: '7'
           pr-lock-reason: ''

.github/workflows/pre-commit_dependencies_notifier.yml

@@ -3,7 +3,7 @@ on:
   pull_request_target:
     paths:
       - requirements.txt
-      - requirements-dev.txt
+      - requirements-opts.txt
       - .pre-commit-config.yaml
 permissions:
  pull-requests: write
@@ -15,5 +15,5 @@ jobs:
       - name: running the check
         uses: Poolitzer/notifier-action@master
         with:
-          notify-message: Hey! Looks like you edited the (dev) requirements or the pre-commit hooks. I'm just a friendly reminder to keep the pre-commit hook versions in sync with the dev requirements and the additional dependencies for the hooks in sync with the requirements :)
+          notify-message: Hey! Looks like you edited the (optional) requirements or the pre-commit hooks. I'm just a friendly reminder to keep the additional dependencies for the hooks in sync with the requirements :)
           repo-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/stale.yml

@@ -0,0 +1,19 @@
+name: 'Mark & close stale questions'
+on:
+  schedule:
+    - cron: '42 2 * * *'
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v6
+        with:
+          # PRs never get stale
+          days-before-stale: 3
+          days-before-close: 2
+          days-before-pr-stale: -1
+          stale-issue-label: 'stale'
+          only-labels: 'question'
+          stale-issue-message: ''
+          close-issue-message: 'This issue has been automatically closed due to inactivity. Feel free to comment in order to reopen or ask again in our Telegram support group at https://t.me/pythontelegrambotgroup.'

.github/workflows/test.yml

@@ -4,7 +4,7 @@ on:
     branches:
       - master
   push:
-    branches: 
+    branches:
       - master
   schedule:
     # Run monday and friday morning at 03:07 - odd time to spread load on GitHub Actions
@@ -16,13 +16,13 @@ jobs:
     runs-on: ${{matrix.os}}
     strategy:
       matrix:
-        python-version: ['3.7', '3.8', '3.9', '3.10']
+        python-version: ['3.7', '3.8', '3.9', '3.10', '3.11']
         os: [ubuntu-latest, windows-latest, macos-latest]
       fail-fast: False
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
@@ -31,31 +31,60 @@ jobs:
           python -W ignore -m pip install -U codecov pytest-cov
           python -W ignore -m pip install -r requirements.txt
           python -W ignore -m pip install -r requirements-dev.txt
+          python -W ignore -m pip install pytest-xdist[psutil]
 
       - name: Test with pytest
-        # We run 3 different suites here
+        # We run 4 different suites here
         # 1. Test just utils.datetime.py without pytz being installed
         # 2. Test just test_no_passport.py without passport dependencies being installed
-        # 3. Test everything else
+        # 3. Test just test_rate_limiter.py without passport dependencies being installed
+        # 4. Test everything else
         # The first & second one are achieved by mocking the corresponding import
         # See test_helpers.py & test_no_passport.py for details
         run: |
+          # Test without passport
           pytest -v --cov -k test_no_passport.py
-          no_passport_exit=$?
-          export TEST_NO_PASSPORT='false'
-          pytest -v --cov --cov-append -k test_helpers.py
-          no_pytz_exit=$?
-          export TEST_NO_PYTZ='false'
-          pytest -v --cov --cov-append
-          full_exit=$?
-          special_exit=$(( no_pytz_exit > no_passport_exit ? no_pytz_exit : no_passport_exit ))
-          global_exit=$(( special_exit > full_exit ? special_exit : full_exit ))
-          exit ${global_exit}
+          status=$?
+
+          # test without pytz
+          pytest -v --cov --cov-append -k test_datetime.py
+          status=$(( $? > status ? $? : status))
+          pytest -v --cov --cov-append -k test_defaults.py
+          status=$(( $? > status ? $? : status))
+
+          # test without pytz & jobqueue
+          pytest -v --cov --cov-append -k test_jobqueue.py
+          pytest -v --cov --cov-append -k test_applicationbuilder.py
+          status=$(( $? > status ? $? : status))
+
+          # Test without ratelimiter
+          pytest -v --cov --cov-append -k test_ratelimiter.py
+          status=$(( $? > status ? $? : status))
+
+          # Test without webhooks
+          pytest -v --cov --cov-append -k test_updater.py
+          status=$(( $? > status ? $? : status))
+
+          # Test without callback-data
+          pytest -v --cov --cov-append -k test_callbackdatacache.py
+          status=$(( $? > status ? $? : status))
+
+          # Test without socks
+          pytest -v --cov --cov-append -k test_request.py
+          status=$(( $? > status ? $? : status))
+
+          # Test the rest
+          export TEST_WITH_OPT_DEPS='true'
+          pip install -r requirements-opts.txt
+          # `-n auto --dist loadfile` uses pytest-xdist to run each test file on a different CPU
+          # worker
+          pytest -v --cov --cov-append -n auto --dist loadfile
+          status=$(( $? > status ? $? : status))
+          exit ${status}
         env:
           JOB_INDEX: ${{ strategy.job-index }}
-          BOTS: W3sidG9rZW4iOiAiNjk2MTg4NzMyOkFBR1Z3RUtmSEhsTmpzY3hFRE5LQXdraEdzdFpfa28xbUMwIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6WldGaU1UUmxNbVF5TnpNeSIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gVHJhdmlzIHVzaW5nIENQeXRob24gMi43IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxMzkwOTgzOTk3IiwgImJvdF91c2VybmFtZSI6ICJAcHRiX3RyYXZpc19jcHl0aG9uXzI3X2JvdCJ9LCB7InRva2VuIjogIjY3MTQ2ODg4NjpBQUdQR2ZjaVJJQlVORmU4MjR1SVZkcTdKZTNfWW5BVE5HdyIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOlpHWXdPVGxrTXpNeE4yWTIiLCAiYm90X25hbWUiOiAiUFRCIHRlc3RzIG9uIFRyYXZpcyB1c2luZyBDUHl0aG9uIDMuNCIsICJzdXBlcl9ncm91cF9pZCI6ICItMTAwMTQ0NjAyMjUyMiIsICJib3RfdXNlcm5hbWUiOiAiQHB0Yl90cmF2aXNfY3B5dGhvbl8zNF9ib3QifSwgeyJ0b2tlbiI6ICI2MjkzMjY1Mzg6QUFGUnJaSnJCN29CM211ekdzR0pYVXZHRTVDUXpNNUNVNG8iLCAicGF5bWVudF9wcm92aWRlcl90b2tlbiI6ICIyODQ2ODUwNjM6VEVTVDpNbU01WVdKaFl6a3hNMlUxIiwgImJvdF9uYW1lIjogIlBUQiB0ZXN0cyBvbiBUcmF2aXMgdXNpbmcgQ1B5dGhvbiAzLjUiLCAic3VwZXJfZ3JvdXBfaWQiOiAiLTEwMDE0OTY5MTc3NTAiLCAiYm90X3VzZXJuYW1lIjogIkBwdGJfdHJhdmlzX2NweXRob25fMzVfYm90In0sIHsidG9rZW4iOiAiNjQwMjA4OTQzOkFBRmhCalFwOXFtM1JUeFN6VXBZekJRakNsZS1Kano1aGNrIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6WXpoa1pUZzFOamMxWXpWbCIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gVHJhdmlzIHVzaW5nIENQeXRob24gMy42IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxMzMzODcxNDYxIiwgImJvdF91c2VybmFtZSI6ICJAcHRiX3RyYXZpc19jcHl0aG9uXzM2X2JvdCJ9LCB7InRva2VuIjogIjY5NTEwNDA4ODpBQUhmenlsSU9qU0lJUy1lT25JMjB5MkUyMEhvZEhzZnotMCIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOk9HUTFNRGd3WmpJd1pqRmwiLCAiYm90X25hbWUiOiAiUFRCIHRlc3RzIG9uIFRyYXZpcyB1c2luZyBDUHl0aG9uIDMuNyIsICJzdXBlcl9ncm91cF9pZCI6ICItMTAwMTQ3ODI5MzcxNCIsICJib3RfdXNlcm5hbWUiOiAiQHB0Yl90cmF2aXNfY3B5dGhvbl8zN19ib3QifSwgeyJ0b2tlbiI6ICI2OTE0MjM1NTQ6QUFGOFdrakNaYm5IcVBfaTZHaFRZaXJGRWxackdhWU9oWDAiLCAicGF5bWVudF9wcm92aWRlcl90b2tlbiI6ICIyODQ2ODUwNjM6VEVTVDpZamM1TlRoaU1tUXlNV1ZoIiwgImJvdF9uYW1lIjogIlBUQiB0ZXN0cyBvbiBUcmF2aXMgdXNpbmcgUHlQeSAyLjciLCAic3VwZXJfZ3JvdXBfaWQiOiAiLTEwMDEzNjM5MzI1NzMiLCAiYm90X3VzZXJuYW1lIjogIkBwdGJfdHJhdmlzX3B5cHlfMjdfYm90In0sIHsidG9rZW4iOiAiNjg0MzM5OTg0OkFBRk1nRUVqcDAxcjVyQjAwN3lDZFZOc2c4QWxOc2FVLWNjIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6TVRBek1UWTNNR1V5TmpnMCIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gVHJhdmlzIHVzaW5nIFB5UHkgMy41IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxNDA3ODM2NjA1IiwgImJvdF91c2VybmFtZSI6ICJAcHRiX3RyYXZpc19weXB5XzM1X2JvdCJ9LCB7InRva2VuIjogIjY5MDA5MTM0NzpBQUZMbVI1cEFCNVljcGVfbU9oN3pNNEpGQk9oMHozVDBUbyIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOlpEaGxOekU1TURrd1lXSmkiLCAiYm90X25hbWUiOiAiUFRCIHRlc3RzIG9uIEFwcFZleW9yIHVzaW5nIENQeXRob24gMy40IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxMjc5NjAwMDI2IiwgImJvdF91c2VybmFtZSI6ICJAcHRiX2FwcHZleW9yX2NweXRob25fMzRfYm90In0sIHsidG9rZW4iOiAiNjk0MzA4MDUyOkFBRUIyX3NvbkNrNTVMWTlCRzlBTy1IOGp4aVBTNTVvb0JBIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6WW1aaVlXWm1NakpoWkdNeSIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gQXBwVmV5b3IgdXNpbmcgQ1B5dGhvbiAyLjciLCAic3VwZXJfZ3JvdXBfaWQiOiAiLTEwMDEyOTMwNzkxNjUiLCAiYm90X3VzZXJuYW1lIjogIkBwdGJfYXBwdmV5b3JfY3B5dGhvbl8yN19ib3QifSwgeyJ0b2tlbiI6ICIxMDU1Mzk3NDcxOkFBRzE4bkJfUzJXQXd1SjNnN29oS0JWZ1hYY2VNbklPeVNjIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6TmpBd056QXpZalZpTkdOayIsICJuYW1lIjogIlBUQiB0ZXN0cyBbMF0iLCAic3VwZXJfZ3JvdXBfaWQiOiAiLTEwMDExODU1MDk2MzYiLCAidXNlcm5hbWUiOiAicHRiXzBfYm90In0sIHsidG9rZW4iOiAiMTA0NzMyNjc3MTpBQUY4bk90ODFGcFg4bGJidno4VWV3UVF2UmZUYkZmQnZ1SSIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOllUVTFOVEk0WkdSallqbGkiLCAibmFtZSI6ICJQVEIgdGVzdHMgWzFdIiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxNDg0Nzk3NjEyIiwgInVzZXJuYW1lIjogInB0Yl8xX2JvdCJ9LCB7InRva2VuIjogIjk3MTk5Mjc0NTpBQUdPa09hVzBOSGpnSXY1LTlqUWJPajR2R3FkaFNGLVV1cyIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOk5XWmtNV1ZoWWpsallqVTUiLCAibmFtZSI6ICJQVEIgdGVzdHMgWzJdIiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxNDAyMjU1MDcwIiwgInVzZXJuYW1lIjogInB0Yl8yX2JvdCJ9XQ==
-          TEST_NO_PYTZ : "true"
-          TEST_NO_PASSPORT: "true"
+          BOTS: W3sidG9rZW4iOiAiNjk2MTg4NzMyOkFBR1Z3RUtmSEhsTmpzY3hFRE5LQXdraEdzdFpfa28xbUMwIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6WldGaU1UUmxNbVF5TnpNeSIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gVHJhdmlzIHVzaW5nIENQeXRob24gMi43IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxMzkwOTgzOTk3IiwgImJvdF91c2VybmFtZSI6ICJAcHRiX3RyYXZpc19jcHl0aG9uXzI3X2JvdCJ9LCB7InRva2VuIjogIjY3MTQ2ODg4NjpBQUdQR2ZjaVJJQlVORmU4MjR1SVZkcTdKZTNfWW5BVE5HdyIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOlpHWXdPVGxrTXpNeE4yWTIiLCAiYm90X25hbWUiOiAiUFRCIHRlc3RzIG9uIFRyYXZpcyB1c2luZyBDUHl0aG9uIDMuNCIsICJzdXBlcl9ncm91cF9pZCI6ICItMTAwMTQ0NjAyMjUyMiIsICJib3RfdXNlcm5hbWUiOiAiQHB0Yl90cmF2aXNfY3B5dGhvbl8zNF9ib3QifSwgeyJ0b2tlbiI6ICI2MjkzMjY1Mzg6QUFGUnJaSnJCN29CM211ekdzR0pYVXZHRTVDUXpNNUNVNG8iLCAicGF5bWVudF9wcm92aWRlcl90b2tlbiI6ICIyODQ2ODUwNjM6VEVTVDpNbU01WVdKaFl6a3hNMlUxIiwgImJvdF9uYW1lIjogIlBUQiB0ZXN0cyBvbiBUcmF2aXMgdXNpbmcgQ1B5dGhvbiAzLjUiLCAic3VwZXJfZ3JvdXBfaWQiOiAiLTEwMDE0OTY5MTc3NTAiLCAiYm90X3VzZXJuYW1lIjogIkBwdGJfdHJhdmlzX2NweXRob25fMzVfYm90In0sIHsidG9rZW4iOiAiNjQwMjA4OTQzOkFBRmhCalFwOXFtM1JUeFN6VXBZekJRakNsZS1Kano1aGNrIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6WXpoa1pUZzFOamMxWXpWbCIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gVHJhdmlzIHVzaW5nIENQeXRob24gMy42IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxMzMzODcxNDYxIiwgImJvdF91c2VybmFtZSI6ICJAcHRiX3RyYXZpc19jcHl0aG9uXzM2X2JvdCJ9LCB7InRva2VuIjogIjY5NTEwNDA4ODpBQUhmenlsSU9qU0lJUy1lT25JMjB5MkUyMEhvZEhzZnotMCIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOk9HUTFNRGd3WmpJd1pqRmwiLCAiYm90X25hbWUiOiAiUFRCIHRlc3RzIG9uIFRyYXZpcyB1c2luZyBDUHl0aG9uIDMuNyIsICJzdXBlcl9ncm91cF9pZCI6ICItMTAwMTQ3ODI5MzcxNCIsICJib3RfdXNlcm5hbWUiOiAiQHB0Yl90cmF2aXNfY3B5dGhvbl8zN19ib3QifSwgeyJ0b2tlbiI6ICI2OTE0MjM1NTQ6QUFGOFdrakNaYm5IcVBfaTZHaFRZaXJGRWxackdhWU9oWDAiLCAicGF5bWVudF9wcm92aWRlcl90b2tlbiI6ICIyODQ2ODUwNjM6VEVTVDpZamM1TlRoaU1tUXlNV1ZoIiwgImJvdF9uYW1lIjogIlBUQiB0ZXN0cyBvbiBUcmF2aXMgdXNpbmcgUHlQeSAyLjciLCAic3VwZXJfZ3JvdXBfaWQiOiAiLTEwMDEzNjM5MzI1NzMiLCAiYm90X3VzZXJuYW1lIjogIkBwdGJfdHJhdmlzX3B5cHlfMjdfYm90In0sIHsidG9rZW4iOiAiNjg0MzM5OTg0OkFBRk1nRUVqcDAxcjVyQjAwN3lDZFZOc2c4QWxOc2FVLWNjIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6TVRBek1UWTNNR1V5TmpnMCIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gVHJhdmlzIHVzaW5nIFB5UHkgMy41IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxNDA3ODM2NjA1IiwgImJvdF91c2VybmFtZSI6ICJAcHRiX3RyYXZpc19weXB5XzM1X2JvdCJ9LCB7InRva2VuIjogIjY5MDA5MTM0NzpBQUZMbVI1cEFCNVljcGVfbU9oN3pNNEpGQk9oMHozVDBUbyIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOlpEaGxOekU1TURrd1lXSmkiLCAiYm90X25hbWUiOiAiUFRCIHRlc3RzIG9uIEFwcFZleW9yIHVzaW5nIENQeXRob24gMy40IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxMjc5NjAwMDI2IiwgImJvdF91c2VybmFtZSI6ICJAcHRiX2FwcHZleW9yX2NweXRob25fMzRfYm90In0sIHsidG9rZW4iOiAiNjk0MzA4MDUyOkFBRUIyX3NvbkNrNTVMWTlCRzlBTy1IOGp4aVBTNTVvb0JBIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6WW1aaVlXWm1NakpoWkdNeSIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gQXBwVmV5b3IgdXNpbmcgQ1B5dGhvbiAyLjciLCAic3VwZXJfZ3JvdXBfaWQiOiAiLTEwMDEyOTMwNzkxNjUiLCAiYm90X3VzZXJuYW1lIjogIkBwdGJfYXBwdmV5b3JfY3B5dGhvbl8yN19ib3QifSwgeyJ0b2tlbiI6ICIxMDU1Mzk3NDcxOkFBRzE4bkJfUzJXQXd1SjNnN29oS0JWZ1hYY2VNbklPeVNjIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6TmpBd056QXpZalZpTkdOayIsICJuYW1lIjogIlBUQiB0ZXN0cyBbMF0iLCAic3VwZXJfZ3JvdXBfaWQiOiAiLTEwMDExODU1MDk2MzYiLCAidXNlcm5hbWUiOiAicHRiXzBfYm90In0sIHsidG9rZW4iOiAiMTA0NzMyNjc3MTpBQUY4bk90ODFGcFg4bGJidno4VWV3UVF2UmZUYkZmQnZ1SSIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOllUVTFOVEk0WkdSallqbGkiLCAibmFtZSI6ICJQVEIgdGVzdHMgWzFdIiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxNDg0Nzk3NjEyIiwgInVzZXJuYW1lIjogInB0Yl8xX2JvdCJ9LCB7InRva2VuIjogIjk3MTk5Mjc0NTpBQUdPa09hVzBOSGpnSXY1LTlqUWJPajR2R3FkaFNGLVV1cyIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOk5XWmtNV1ZoWWpsallqVTUiLCAibmFtZSI6ICJQVEIgdGVzdHMgWzJdIiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxNDAyMjU1MDcwIiwgInVzZXJuYW1lIjogInB0Yl8yX2JvdCJ9LCB7InRva2VuIjogIjU1MTg2NDU0MTE6QUFHdzBxaEs3ZTRHbmoxWjJjc1BBQzdaYWtvTWs1NkVKZmsiLCAicGF5bWVudF9wcm92aWRlcl90b2tlbiI6ICIyODQ2ODUwNjM6VEVTVDpNRE0wT1RCbE9UUXpNVEU1IiwgIm5hbWUiOiAiUFRCIFRlc3QgQm90IFszXSIsICJzdXBlcl9ncm91cF9pZCI6ICItMTAwMTgwMzgxMDE5NiIsICJ1c2VybmFtZSI6ICJwdGJfdGVzdF8wM19ib3QifSwgeyJ0b2tlbiI6ICI1NzM3MDE4MzU2OkFBSDEzOFN1aUtRRjBMRENXc2ZnV2VYZmpKNWQ2M2tDV0xBIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6TjJWaVpqUmxaak01TlRNdyIsICJuYW1lIjogIlBUQiBUZXN0IEJvdCBbNF0iLCAidXNlcm5hbWUiOiAicHRiX3Rlc3RfMDRfYm90IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxODQyNDM5NjQxIn0sIHsidG9rZW4iOiAiNTc0NDY0NDUyMjpBQUVBZHNyRjBoQzZwNkhVTzBQMDFROGJfakNoVTUyWEctTSIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOlpqSmtZVGd5TmpnMlpHRTAiLCAibmFtZSI6ICJQVEIgVGVzdCBCb3QgWzVdIiwgInVzZXJuYW1lIjogInB0Yl90ZXN0XzA1X2JvdCIsICJzdXBlcl9ncm91cF9pZCI6ICItMTAwMTg1NTM2MDk4NiJ9XQ==
+          TEST_WITH_OPT_DEPS : "false"
           TEST_BUILD: "true"
         shell: bash --noprofile --norc {0}
 
@@ -76,13 +105,14 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
         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.txt
+          python -W ignore -m pip install -r requirements-opts.txt
           python -W ignore -m pip install -r requirements-dev.txt
       - name: Compare to official api
         run: |

.pre-commit-config.yaml

@@ -1,25 +1,26 @@
-# Make sure that
-#   * the revs specified here match requirements-dev.txt
-#   * the additional_dependencies here match requirements.txt
+# Make sure that the additional_dependencies here match requirements.txt
 
 ci:
     autofix_prs: false
     autoupdate_schedule: monthly
+    # We currently only need this behavior on the v13.x branch were we have the vendored urllib
+    # TODO: Remove once we discontinue v13
+    submodules: true
 
 repos:
 -   repo: https://github.com/psf/black
-    rev: 22.3.0
+    rev: 22.10.0
     hooks:
     -   id: black
         args:
         - --diff
         - --check
--   repo: https://gitlab.com/pycqa/flake8
-    rev: 4.0.1
+-   repo: https://github.com/PyCQA/flake8
+    rev: 6.0.0
     hooks:
     -   id: flake8
 -   repo: https://github.com/PyCQA/pylint
-    rev: v2.13.8
+    rev: v2.15.8
     hooks:
     -   id: pylint
         files: ^(telegram|examples)/.*\.py$
@@ -30,26 +31,27 @@ repos:
           - --jobs=0
 
         additional_dependencies:
-          - httpx~=0.22.0
-          - tornado~=6.1
+          - httpx~=0.23.0
+          - tornado~=6.2
           - APScheduler~=3.9.1
-          - cachetools~=5.0.0
+          - cachetools~=5.2.0
+          - aiolimiter~=1.0.0
           - . # this basically does `pip install -e .`
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.950
+    rev: v0.991
     hooks:
     -   id: mypy
         name: mypy-ptb
         files: ^telegram/.*\.py$
         additional_dependencies:
-          - types-ujson
           - types-pytz
           - types-cryptography
           - types-cachetools
-          - httpx~=0.22.0
-          - tornado~=6.1
+          - httpx~=0.23.0
+          - tornado~=6.2
           - APScheduler~=3.9.1
-          - cachetools~=5.0.0
+          - cachetools~=5.2.0
+          - aiolimiter~=1.0.0
           - . # this basically does `pip install -e .`
     - id: mypy
       name: mypy-examples
@@ -58,12 +60,12 @@ repos:
         - --no-strict-optional
         - --follow-imports=silent
       additional_dependencies:
-        - tornado~=6.1
+        - tornado~=6.2
         - APScheduler~=3.9.1
-        - cachetools~=5.0.0
+        - cachetools~=5.2.0
         - . # this basically does `pip install -e .`
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v2.32.0
+    rev: v3.3.0
     hooks:
     -   id: pyupgrade
         files: ^(telegram|examples|tests)/.*\.py$
@@ -74,4 +76,6 @@ repos:
     hooks:
     -   id: isort
         name: isort
-        args: ["--diff"]  # -diff will not apply the changes, just show them
+        args:
+        - --diff
+        - --check

.readthedocs.yml

@@ -15,8 +15,37 @@ formats:
 
 # Optionally set the version of Python and requirements required to build your docs
 python:
-   version: 3
    install:
      - method: pip
        path: .
      - requirements: docs/requirements-docs.txt
+
+build:
+   os: ubuntu-22.04
+   tools:
+      python: "3"  # latest stable cpython version
+
+search:
+   ranking:  # bump up rank of commonly searched pages: (default: 0, values range from -10 to 10)
+      telegram.bot.html: 7
+      telegram.message.html: 3
+      telegram.update.html: 3
+      telegram.user.html: 2
+      telegram.chat.html: 2
+      telegram.ext.application.html: 3
+      telegram.ext.filters.html: 3
+      telegram.ext.callbackcontext.html: 2
+      telegram.ext.inlinekeyboardbutton.html: 1
+
+      telegram.passport*.html: -7
+
+   ignore:
+      - changelog.html
+      - coc.html
+      - bot_methods.html#
+      - bot_methods.html
+      # Defaults
+      - search.html
+      - search/index.html
+      - 404.html
+      - 404/index.html'

AUTHORS.rst

@@ -9,6 +9,8 @@ The current development team includes
 - `Poolitzer <https://github.com/Poolitzer>`_ (community liaison)
 - `Shivam <https://github.com/Starry69>`_
 - `Harshil <https://github.com/harshil21>`_
+- `Dmitry Kolomatskiy <https://github.com/lemontree210>`_
+- `Aditya <https://github.com/clot27>`_
 
 Emeritus maintainers include
 `Jannes Höke <https://github.com/jh0ker>`_ (`@jh0ker <https://t.me/jh0ker>`_ on Telegram),
@@ -28,7 +30,9 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Avanatiker <https://github.com/Avanatiker>`_
 - `Balduro <https://github.com/Balduro>`_
 - `Bibo-Joshi <https://github.com/Bibo-Joshi>`_
+- `Biruk Alamirew <https://github.com/BAcode-X>`_
 - `bimmlerd <https://github.com/bimmlerd>`_
+- `cyc8 <https://github.com/cyc8>`_ 
 - `d-qoi <https://github.com/d-qoi>`_
 - `daimajia <https://github.com/daimajia>`_
 - `Daniel Reed <https://github.com/nmlorg>`_
@@ -45,6 +49,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Evan Haberecht <https://github.com/habereet>`_
 - `Evgeny Denisov <https://github.com/eIGato>`_
 - `evgfilim1 <https://github.com/evgfilim1>`_
+- `ExalFabu <https://github.com/ExalFabu>`_
 - `franciscod <https://github.com/franciscod>`_
 - `gamgi <https://github.com/gamgi>`_
 - `Gauthamram Ravichandran <https://github.com/GauthamramRavichandran>`_
@@ -70,6 +75,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `macrojames <https://github.com/macrojames>`_
 - `Matheus Lemos <https://github.com/mlemosf>`_
 - `Michael Elovskikh <https://github.com/wronglink>`_
+- `miles <https://github.com/miles170>`_
 - `Mischa Krüger <https://github.com/Makman2>`_
 - `naveenvhegde <https://github.com/naveenvhegde>`_
 - `neurrone <https://github.com/neurrone>`_
@@ -84,6 +90,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Paradox <https://github.com/paradox70>`_
 - `Patrick Hofmann <https://github.com/PH89>`_
 - `Paul Larsen <https://github.com/PaulSonOfLars>`_
+- `Pawan <https://github.com/pawanrai9999>`_
 - `Pieter Schutz <https://github.com/eldinnie>`_
 - `Piraty <https://github.com/piraty>`_
 - `Poolitzer <https://github.com/Poolitzer>`_
@@ -105,8 +112,10 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Vorobjev Simon <https://github.com/simonvorobjev>`_
 - `Wagner Macedo <https://github.com/wagnerluis1982>`_
 - `wjt <https://github.com/wjt>`_
+- `Yaw Danso <https://github.com/dglitxh>`_
 - `zeroone2numeral2 <https://github.com/zeroone2numeral2>`_
 - `zeshuaro <https://github.com/zeshuaro>`_
 - `zpavloudis <https://github.com/zpavloudis>`_
 
+
 Please add yourself here alphabetically when you submit your first pull request.

CHANGES.rst

@@ -1,6 +1,442 @@
 =========
 Changelog
 =========
+Version 20.0b0
+==============
+*Released 2022-12-15*
+
+This is the technical changelog for version 20.0b0. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Make `TelegramObject` Immutable (`#3249`_)
+
+Minor Changes, Documentation Improvements and CI
+------------------------------------------------
+
+- Reduce Code Duplication in Testing ``Defaults`` (`#3419`_)
+- Add Notes and Warnings About Optional Dependencies (`#3393`_)
+- Simplify Internals of ``Bot`` Methods (`#3396`_)
+- Reduce Code Duplication in Several ``Bot`` Methods (`#3385`_)
+- Documentation Improvements (`#3386`_, `#3395`_, `#3398`_, `#3403`_)
+
+Dependencies
+------------
+
+- Bump ``pytest-xdist`` from 3.0.2 to 3.1.0 (`#3415`_)
+- Bump ``pytest-asyncio`` from 0.20.2 to 0.20.3 (`#3417`_)
+- ``pre-commit`` autoupdate (`#3409`_)
+
+.. _`#3249`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3249
+.. _`#3419`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3419
+.. _`#3393`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3393
+.. _`#3396`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3396
+.. _`#3385`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3385
+.. _`#3386`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3386
+.. _`#3395`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3395
+.. _`#3398`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3398
+.. _`#3403`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3403
+.. _`#3415`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3415
+.. _`#3417`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3417
+.. _`#3409`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3409
+
+Version 20.0a6
+==============
+*Released 2022-11-24*
+
+This is the technical changelog for version 20.0a6. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Bug Fixes
+---------
+
+- Only Persist Arbitrary ``callback_data`` if ``ExtBot.callback_data_cache`` is Present (`#3384`_)
+- Improve Backwards Compatibility of ``TelegramObjects`` Pickle Behavior (`#3382`_)
+- Fix Naming and Keyword Arguments of ``File.download_*`` Methods (`#3380`_)
+- Fix Return Value Annotation of ``Chat.create_forum_topic`` (`#3381`_)
+
+.. _`#3384`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3384
+.. _`#3382`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3382
+.. _`#3380`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3380
+.. _`#3381`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3381
+
+Version 20.0a5
+==============
+*Released 2022-11-22*
+
+This is the technical changelog for version 20.0a5. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- API 6.3 (`#3346`_, `#3343`_, `#3342`_, `#3360`_)
+- Explicit ``local_mode`` Setting (`#3154`_)
+- Make Almost All 3rd Party Dependencies Optional (`#3267`_)
+- Split ``File.download`` Into ``File.download_to_drive`` And ``File.download_to_memory`` (`#3223`_)
+
+New Features
+------------
+
+- Add Properties for API Settings of ``Bot`` (`#3247`_)
+- Add ``chat_id`` and ``username`` Parameters to ``ChatJoinRequestHandler`` (`#3261`_)
+- Introduce ``TelegramObject.api_kwargs`` (`#3233`_)
+- Add Two Constants Related to Local Bot API Servers (`#3296`_)
+- Add ``recursive`` Parameter to ``TelegramObject.to_dict()`` (`#3276`_)
+- Overhaul String Representation of ``TelegramObject`` (`#3234`_)
+- Add Methods ``Chat.mention_{html, markdown, markdown_v2}`` (`#3308`_)
+- Add ``constants.MessageLimit.DEEP_LINK_LENGTH`` (`#3315`_)
+- Add Shortcut Parameters ``caption``, ``parse_mode`` and ``caption_entities`` to ``Bot.send_media_group`` (`#3295`_)
+- Add Several New Enums To Constants (`#3351`_)
+
+Bug Fixes
+---------
+
+- Fix ``CallbackQueryHandler`` Not Handling Non-String Data Correctly With Regex Patterns (`#3252`_)
+- Fix Defaults Handling in ``Bot.answer_web_app_query`` (`#3362`_)
+
+Documentation Improvements
+--------------------------
+
+- Update PR Template (`#3361`_)
+- Document Dunder Methods of ``TelegramObject`` (`#3319`_)
+- Add Several References to Wiki pages (`#3306`_)
+- Overhaul Search bar (`#3218`_)
+- Unify Documentation of Arguments and Attributes of Telegram Classes (`#3217`_, `#3292`_, `#3303`_, `#3312`_, `#3314`_)
+- Several Smaller Improvements (`#3214`_, `#3271`_, `#3289`_, `#3326`_, `#3370`_, `#3376`_, `#3366`_)
+
+Minor Changes, Documentation Improvements and CI
+------------------------------------------------
+
+- Improve Warning About Unknown ``ConversationHandler`` States (`#3242`_)
+- Switch from Stale Bot to ``GitHub`` Actions (`#3243`_)
+- Bump Python 3.11 to RC2 in Test Matrix (`#3246`_)
+- Make ``Job.job`` a Property and Make ``Jobs`` Hashable (`#3250`_)
+- Skip ``JobQueue`` Tests on Windows Again (`#3280`_)
+- Read-Only ``CallbackDataCache`` (`#3266`_)
+- Type Hinting Fix for ``Message.effective_attachment`` (`#3294`_)
+- Run Unit Tests in Parallel (`#3283`_)
+- Update Test Matrix to Use Stable Python 3.11 (`#3313`_)
+- Don't Edit Objects In-Place When Inserting ``ext.Defaults`` (`#3311`_)
+- Add a Test for ``MessageAttachmentType`` (`#3335`_)
+- Add Three New Test Bots (`#3347`_)
+- Improve Unit Tests Regarding ``ChatMemberUpdated.difference`` (`#3352`_)
+- Flaky Unit Tests: Use ``pytest`` Marker (`#3354`_)
+- Fix ``DeepSource`` Issues (`#3357`_)
+- Handle Lists and Tuples and Datetimes Directly in ``TelegramObject.to_dict`` (`#3353`_)
+- Update Meta Config (`#3365`_)
+- Merge ``ChatDescriptionLimit`` Enum Into ``ChatLimit`` (`#3377`_)
+
+Dependencies
+------------
+
+- Bump ``pytest`` from 7.1.2 to 7.1.3 (`#3228`_)
+- ``pre-commit`` Updates (`#3221`_)
+- Bump ``sphinx`` from 5.1.1 to 5.2.3 (`#3269`_)
+- Bump ``furo`` from 2022.6.21 to 2022.9.29 (`#3268`_)
+- Bump ``actions/stale`` from 5 to 6 (`#3277`_)
+- ``pre-commit`` autoupdate (`#3282`_)
+- Bump ``sphinx`` from 5.2.3 to 5.3.0 (`#3300`_)
+- Bump ``pytest-asyncio`` from 0.19.0 to 0.20.1 (`#3299`_)
+- Bump ``pytest`` from 7.1.3 to 7.2.0 (`#3318`_)
+- Bump ``pytest-xdist`` from 2.5.0 to 3.0.2 (`#3317`_)
+- ``pre-commit`` autoupdate (`#3325`_)
+- Bump ``pytest-asyncio`` from 0.20.1 to 0.20.2 (`#3359`_)
+- Update ``httpx`` requirement from ~=0.23.0 to ~=0.23.1 (`#3373`_)
+
+.. _`#3346`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3346
+.. _`#3343`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3343
+.. _`#3342`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3342
+.. _`#3360`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3360
+.. _`#3154`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3154
+.. _`#3267`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3267
+.. _`#3223`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3223
+.. _`#3247`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3247
+.. _`#3261`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3261
+.. _`#3233`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3233
+.. _`#3296`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3296
+.. _`#3276`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3276
+.. _`#3234`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3234
+.. _`#3308`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3308
+.. _`#3315`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3315
+.. _`#3295`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3295
+.. _`#3351`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3351
+.. _`#3252`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3252
+.. _`#3362`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3362
+.. _`#3361`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3361
+.. _`#3319`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3319
+.. _`#3306`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3306
+.. _`#3218`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3218
+.. _`#3217`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3217
+.. _`#3292`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3292
+.. _`#3303`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3303
+.. _`#3312`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3312
+.. _`#3314`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3314
+.. _`#3214`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3214
+.. _`#3271`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3271
+.. _`#3289`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3289
+.. _`#3326`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3326
+.. _`#3370`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3370
+.. _`#3376`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3376
+.. _`#3366`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3366
+.. _`#3242`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3242
+.. _`#3243`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3243
+.. _`#3246`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3246
+.. _`#3250`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3250
+.. _`#3280`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3280
+.. _`#3266`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3266
+.. _`#3294`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3294
+.. _`#3283`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3283
+.. _`#3313`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3313
+.. _`#3311`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3311
+.. _`#3335`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3335
+.. _`#3347`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3347
+.. _`#3352`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3352
+.. _`#3354`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3354
+.. _`#3357`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3357
+.. _`#3353`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3353
+.. _`#3365`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3365
+.. _`#3377`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3377
+.. _`#3228`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3228
+.. _`#3221`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3221
+.. _`#3269`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3269
+.. _`#3268`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3268
+.. _`#3277`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3277
+.. _`#3282`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3282
+.. _`#3300`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3300
+.. _`#3299`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3299
+.. _`#3318`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3318
+.. _`#3317`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3317
+.. _`#3325`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3325
+.. _`#3359`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3359
+.. _`#3373`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3373
+
+Version 20.0a4
+==============
+*Released 2022-08-27*
+
+This is the technical changelog for version 20.0a4. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Hot Fixes
+---------
+
+* Fix a Bug in ``setup.py`` Regarding Optional Dependencies (`#3209`_)
+
+.. _`#3209`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3209
+
+Version 20.0a3
+==============
+*Released 2022-08-27*
+
+This is the technical changelog for version 20.0a3. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Full Support for API 6.2 (`#3195`_)
+
+New Features
+------------
+
+- New Rate Limiting Mechanism (`#3148`_)
+- Make ``chat/user_data`` Available in Error Handler for Errors in Jobs (`#3152`_)
+- Add ``Application.post_shutdown`` (`#3126`_)
+
+Bug Fixes
+---------
+
+- Fix ``helpers.mention_markdown`` for Markdown V1 and Improve Related Unit Tests (`#3155`_)
+- Add ``api_kwargs`` Parameter to ``Bot.log_out`` and Improve Related Unit Tests (`#3147`_)
+- Make ``Bot.delete_my_commands`` a Coroutine Function (`#3136`_)
+- Fix ``ConversationHandler.check_update`` not respecting ``per_user`` (`#3128`_)
+
+Minor Changes, Documentation Improvements and CI
+------------------------------------------------
+
+- Add Python 3.11 to Test Suite & Adapt Enum Behaviour (`#3168`_)
+- Drop Manual Token Validation (`#3167`_)
+- Simplify Unit Tests for ``Bot.send_chat_action`` (`#3151`_)
+- Drop ``pre-commit`` Dependencies from ``requirements-dev.txt`` (`#3120`_)
+- Change Default Values for ``concurrent_updates`` and ``connection_pool_size`` (`#3127`_)
+- Documentation Improvements (`#3139`_, `#3153`_, `#3135`_)
+- Type Hinting Fixes (`#3202`_)
+
+Dependencies
+------------
+
+- Bump ``sphinx`` from 5.0.2 to 5.1.1 (`#3177`_)
+- Update ``pre-commit`` Dependencies (`#3085`_)
+- Bump ``pytest-asyncio`` from 0.18.3 to 0.19.0 (`#3158`_)
+- Update ``tornado`` requirement from ~=6.1 to ~=6.2 (`#3149`_)
+- Bump ``black`` from 22.3.0 to 22.6.0 (`#3132`_)
+- Bump ``actions/setup-python`` from 3 to 4 (`#3131`_)
+
+.. _`#3195`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3195
+.. _`#3148`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3148
+.. _`#3152`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3152
+.. _`#3126`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3126
+.. _`#3155`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3155
+.. _`#3147`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3147
+.. _`#3136`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3136
+.. _`#3128`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3128
+.. _`#3168`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3168
+.. _`#3167`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3167
+.. _`#3151`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3151
+.. _`#3120`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3120
+.. _`#3127`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3127
+.. _`#3139`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3139
+.. _`#3153`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3153
+.. _`#3135`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3135
+.. _`#3202`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3202
+.. _`#3177`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3177
+.. _`#3085`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3085
+.. _`#3158`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3158
+.. _`#3149`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3149
+.. _`#3132`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3132
+.. _`#3131`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3131
+
+Version 20.0a2
+==============
+*Released 2022-06-27*
+
+This is the technical changelog for version 20.0a2. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes
+-------------
+
+- Full Support for API 6.1 (`#3112`_)
+
+New Features
+------------
+
+- Add Additional Shortcut Methods to ``Chat`` (`#3115`_)
+- Mermaid-based Example State Diagrams (`#3090`_)
+
+Minor Changes, Documentation Improvements and CI
+------------------------------------------------
+
+- Documentation Improvements (`#3103`_, `#3121`_, `#3098`_)
+- Stabilize CI (`#3119`_)
+- Bump ``pyupgrade`` from 2.32.1 to 2.34.0 (`#3096`_)
+- Bump ``furo`` from 2022.6.4 to 2022.6.4.1 (`#3095`_)
+- Bump ``mypy`` from 0.960 to 0.961 (`#3093`_)
+
+.. _`#3112`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3112
+.. _`#3115`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3115
+.. _`#3090`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3090
+.. _`#3103`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3103
+.. _`#3121`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3121
+.. _`#3098`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3098
+.. _`#3119`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3119
+.. _`#3096`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3096
+.. _`#3095`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3095
+.. _`#3093`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3093
+
+Version 20.0a1
+==============
+*Released 2022-06-09*
+
+This is the technical changelog for version 20.0a1. More elaborate release notes can be found in the news channel `@pythontelegrambotchannel <https://t.me/pythontelegrambotchannel>`_.
+
+Major Changes:
+--------------
+
+- Drop Support for ``ujson`` and instead ``BaseRequest.parse_json_payload`` (`#3037`_, `#3072`_)
+- Drop ``InputFile.is_image`` (`#3053`_)
+- Drop Explicit Type conversions in ``__init__`` s (`#3056`_)
+- Handle List-Valued Attributes More Consistently (`#3057`_)
+- Split ``{Command, Prefix}Handler`` And Make Attributes Immutable (`#3045`_)
+- Align Behavior Of ``JobQueue.run_daily`` With ``cron`` (`#3046`_)
+- Make PTB Specific  Keyword-Only Arguments for PTB Specific in Bot methods (`#3035`_)
+- Adjust Equality Comparisons to Fit Bot API 6.0 (`#3033`_)
+- Add Tuple Based Version Info (`#3030`_)- Improve Type Annotations for ``CallbackContext`` and Move Default Type Alias to ``ContextTypes.DEFAULT_TYPE`` (`#3017`_, `#3023`_)
+- Rename ``Job.context`` to ``Job.data`` (`#3028`_)
+- Rename ``Handler`` to ``BaseHandler`` (`#3019`_)
+
+New Features:
+-------------
+
+- Add ``Application.post_init`` (`#3078`_)
+- Add Arguments ``chat/user_id`` to ``CallbackContext`` And Example On Custom Webhook Setups (`#3059`_)
+- Add Convenience Property ``Message.id`` (`#3077`_)
+- Add Example for ``WebApp`` (`#3052`_)
+- Rename ``telegram.bot_api_version`` to ``telegram.__bot_api_version__`` (`#3030`_)
+
+Bug Fixes:
+----------
+
+- Fix Non-Blocking Entry Point in ``ConversationHandler`` (`#3068`_)
+- Escape Backslashes in ``escape_markdown``  (`#3055`_)
+
+Dependencies:
+-------------
+
+- Update ``httpx`` requirement from ~=0.22.0 to ~=0.23.0 (`#3069`_)
+- Update ``cachetools`` requirement from ~=5.0.0 to ~=5.2.0 (`#3058`_, `#3080`_)
+
+Minor Changes, Documentation Improvements and CI:
+-------------------------------------------------
+
+- Move Examples To Documentation (`#3089`_)
+- Documentation Improvements and Update Dependencies (`#3010`_, `#3007`_, `#3012`_, `#3067`_, `#3081`_, `#3082`_)
+- Improve Some Unit Tests (`#3026`_)
+- Update Code Quality dependencies (`#3070`_, `#3032`_,`#2998`_, `#2999`_)
+- Don't Set Signal Handlers On Windows By Default (`#3065`_)
+- Split ``{Command, Prefix}Handler`` And Make Attributes Immutable (`#3045`_)
+- Apply ``isort`` and Update ``pre-commit.ci`` Configuration (`#3049`_)
+- Adjust ``pre-commit`` Settings for ``isort`` (`#3043`_)
+- Add Version Check to Examples (`#3036`_)
+- Use ``Collection`` Instead of ``List`` and ``Tuple`` (`#3025`_)
+- Remove Client-Side Parameter Validation (`#3024`_)
+- Don't Pass Default Values of Optional Parameters to Telegram (`#2978`_)
+- Stabilize ``Application.run_*`` on Python 3.7 (`#3009`_)
+- Ignore Code Style Commits in ``git blame`` (`#3003`_)
+- Adjust Tests to Changed API Behavior (`#3002`_)
+
+.. _`#2978`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2978
+.. _`#2998`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2998
+.. _`#2999`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2999
+.. _`#3002`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3002
+.. _`#3003`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3003
+.. _`#3007`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3007
+.. _`#3009`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3009
+.. _`#3010`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3010
+.. _`#3012`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3012
+.. _`#3017`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3017
+.. _`#3019`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3019
+.. _`#3023`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3023
+.. _`#3024`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3024
+.. _`#3025`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3025
+.. _`#3026`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3026
+.. _`#3028`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3028
+.. _`#3030`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3030
+.. _`#3032`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3032
+.. _`#3033`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3033
+.. _`#3035`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3035
+.. _`#3036`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3036
+.. _`#3037`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3037
+.. _`#3043`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3043
+.. _`#3045`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3045
+.. _`#3046`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3046
+.. _`#3049`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3049
+.. _`#3052`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3052
+.. _`#3053`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3053
+.. _`#3055`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3055
+.. _`#3056`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3056
+.. _`#3057`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3057
+.. _`#3058`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3058
+.. _`#3059`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3059
+.. _`#3065`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3065
+.. _`#3067`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3067
+.. _`#3068`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3068
+.. _`#3069`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3069
+.. _`#3070`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3070
+.. _`#3072`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3072
+.. _`#3077`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3077
+.. _`#3078`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3078
+.. _`#3080`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3080
+.. _`#3081`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3081
+.. _`#3082`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3082
+.. _`#3089`: https://github.com/python-telegram-bot/python-telegram-bot/pull/3089
 
 Version 20.0a0
 ==============
@@ -72,9 +508,9 @@ New Features:
    by `DonalDuck004 <https://github.com/DonalDuck004>`__)
 -  Add Method ``drop_chat/user_data`` to ``Dispatcher`` and Persistence
    (`#2852 <https://github.com/python-telegram-bot/python-telegram-bot/pull/2852>`__)
--  Add methods ``ChatPermissions.{all, no}_permissions`` ([#2948]
+-  Add methods ``ChatPermissions.{all, no}_permissions`` (`#2948 <https://github.com/python-telegram-bot/python-telegram-bot/pull/2948>`__)
 -  Full Support for API 6.0
-   (`#2956 <https://github.com/python-telegram-bot/python-telegram-bot/pull/2956>`__)(https://github.com/python-telegram-bot/python-telegram-bot/pull/2948))
+   (`#2956 <https://github.com/python-telegram-bot/python-telegram-bot/pull/2956>`__)
 -  Add Python 3.10 to Test Suite
    (`#2968 <https://github.com/python-telegram-bot/python-telegram-bot/pull/2968>`__)
 
@@ -1520,7 +1956,7 @@ Changes
 - Lots of small improvements to our tests and documentation.
 
 
-.. _`see docs`: http://python-telegram-bot.readthedocs.io/en/stable/telegram.ext.dispatcher.html#telegram.ext.Dispatcher.add_handler
+.. _`see docs`: https://docs.python-telegram-bot.org/en/stable/telegram.ext.dispatcher.html#telegram.ext.Dispatcher.add_handler
 .. _`#777`: https://github.com/python-telegram-bot/python-telegram-bot/pull/777
 .. _`#806`: https://github.com/python-telegram-bot/python-telegram-bot/pull/806
 .. _`#766`: https://github.com/python-telegram-bot/python-telegram-bot/pull/766
@@ -1762,7 +2198,7 @@ Pre-version 7.0
 
 - Implement Bot API 2.0
 - Almost complete recode of ``Dispatcher``
-- Please read the `Transistion Guide to 4.0 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Transistion-guide-to-Version-4.0>`_
+- Please read the `Transistion Guide to 4.0 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Transition-guide-to-Version-4.0>`_
 
 **2016-03-22**
 

CODE_OF_CONDUCT.rst

@@ -49,4 +49,4 @@ Project maintainers who do not follow or enforce the Code of Conduct in good fai
 Attribution
 ===========
 
-This Code of Conduct is adapted from the `Contributor Covenant <http://contributor-covenant.org>`_, version 1.4, available at `http://contributor-covenant.org/version/1/4 <http://contributor-covenant.org/version/1/4/>`_.
+This Code of Conduct is adapted from the `Contributor Covenant <https://www.contributor-covenant.org>`_, version 1.4, available at `https://www.contributor-covenant.org/version/1/4 <https://www.contributor-covenant.org/version/1/4/>`_.

MANIFEST.in

@@ -1 +1 @@
-include LICENSE LICENSE.lesser Makefile requirements.txt README_RAW.rst telegram/py.typed
+include LICENSE LICENSE.lesser requirements.txt requirements-opts.txt README_RAW.rst telegram/py.typed

README.rst

@@ -1,7 +1,7 @@
 ..
     Make sure to apply any changes to this file to README_RAW.rst as well!
 
-.. image:: https://github.com/python-telegram-bot/logos/blob/master/logo-text/png/ptb-logo-text_768.png?raw=true
+.. image:: https://raw.githubusercontent.com/python-telegram-bot/logos/master/logo-text/png/ptb-logo-text_768.png
    :align: center
    :target: https://python-telegram-bot.org
    :alt: python-telegram-bot Logo
@@ -14,7 +14,7 @@
    :target: https://pypi.org/project/python-telegram-bot/
    :alt: Supported Python versions
 
-.. image:: https://img.shields.io/badge/Bot%20API-6.0-blue?logo=telegram
+.. image:: https://img.shields.io/badge/Bot%20API-6.3-blue?logo=telegram
    :target: https://core.telegram.org/bots/api-changelog
    :alt: Supported Bot API versions
 
@@ -23,7 +23,7 @@
    :alt: PyPi Package Monthly Download
 
 .. image:: https://readthedocs.org/projects/python-telegram-bot/badge/?version=stable
-   :target: https://python-telegram-bot.readthedocs.io/en/stable/
+   :target: https://docs.python-telegram-bot.org/en/stable/
    :alt: Documentation Status
 
 .. image:: https://img.shields.io/pypi/l/python-telegram-bot.svg
@@ -35,15 +35,15 @@
    :alt: Github Actions workflow
 
 .. image:: https://codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg
-   :target: https://codecov.io/gh/python-telegram-bot/python-telegram-bot
+   :target: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot
    :alt: Code coverage
 
-.. image:: http://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg
-   :target: http://isitmaintained.com/project/python-telegram-bot/python-telegram-bot
+.. image:: https://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg
+   :target: https://isitmaintained.com/project/python-telegram-bot/python-telegram-bot
    :alt: Median time to resolve an issue
 
 .. image:: https://api.codacy.com/project/badge/Grade/99d901eaa09b44b4819aec05c330c968
-   :target: https://www.codacy.com/app/python-telegram-bot/python-telegram-bot?utm_source=github.com&utm_medium=referral&utm_content=python-telegram-bot/python-telegram-bot&utm_campaign=Badge_Grade
+   :target: https://app.codacy.com/gh/python-telegram-bot/python-telegram-bot/dashboard
    :alt: Code quality: Codacy
 
 .. image:: https://deepsource.io/gh/python-telegram-bot/python-telegram-bot.svg/?label=active+issues
@@ -93,7 +93,7 @@ Installing both ``python-telegram-bot`` and ``python-telegram-bot-raw`` in conju
 Telegram API support
 ====================
 
-All types and methods of the Telegram Bot API **6.0** are supported.
+All types and methods of the Telegram Bot API **6.2** are supported.
 
 Installing
 ==========
@@ -119,26 +119,35 @@ Dependencies & Their Versions
 
 ``python-telegram-bot`` tries to use as few 3rd party dependencies as possible.
 However, for some features using a 3rd party library is more sane than implementing the functionality again.
-The dependencies are:
+As these features are *optional*, the corresponding 3rd party dependencies are not installed by default.
+Instead, they are listed as optional dependencies.
+This allows to avoid unnecessary dependency conflicts for users who don't need the optional features.
 
-* `httpx ~= 0.22.0 <https://www.python-httpx.org>`_ for ``telegram.request.HTTPXRequest``, the default networking backend
-* `tornado~=6.1 <https://www.tornadoweb.org/en/stable/>`_ for ``telegram.ext.Updater.start_webhook``
-* `cachetools~=5.0.0 <https://cachetools.readthedocs.io/en/latest/>`_ for ``telegram.ext.CallbackDataCache``
-* `APScheduler~=3.9.1 <https://apscheduler.readthedocs.io/en/3.x/>`_ for ``telegram.ext.JobQueue``
+The only required dependency is `httpx ~= 0.23.0 <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.
-To minimize dependency conflicts, we try to be liberal in terms of version requirements on the dependencies.
+To minimize dependency conflicts, we try to be liberal in terms of version requirements on the (optional) dependencies.
 On the other hand, we have to ensure stability of ``python-telegram-bot``, which is why we do apply version bounds.
 If you encounter dependency conflicts due to these bounds, feel free to reach out.
 
 Optional Dependencies
----------------------
+#####################
 
 PTB can be installed with optional dependencies:
 
-* ``pip install python-telegram-bot[passport]`` installs the `cryptography>=3.0 <https://cryptography.io>`_ library. Use this, if you want to use Telegram Passport related functionality.
-* ``pip install python-telegram-bot[json]`` installs the `ujson>=4.0.0 <https://pypi.org/project/ujson/>`_ library. It will then be used for JSON de- & encoding, which can bring speed up compared to the standard `json <https://docs.python.org/3/library/json.html>`_ library.
+* ``pip install python-telegram-bot[passport]`` installs the `cryptography>=3.0 <https://cryptography.io/en/stable>`_ library. Use this, if you want to use Telegram Passport related functionality.
 * ``pip install python-telegram-bot[socks]`` installs ``httpx[socks]``. Use this, if you want to work behind a Socks5 server.
+* ``pip install python-telegram-bot[rate-limiter]`` installs ``aiolimiter~=1.0.0``. Use this, if you want to use ``telegram.ext.AIORateLimiter``.
+* ``pip install python-telegram-bot[webhooks]`` installs the `tornado~=6.2 <https://www.tornadoweb.org/en/stable/>`_ library. Use this, if you want to use ``telegram.ext.Updater.start_webhook``/``telegram.ext.Application.start_webhook``.
+* ``pip install python-telegram-bot[callback-data]`` installs the `cachetools~=5.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.9.1 <https://apscheduler.readthedocs.io/en/3.x/>`_ library and enforces `pytz>=2018.6 <https://pypi.org/project/pytz/>`_, where ``pytz`` is a dependency of ``APScheduler``. Use this, if you want to use the ``telegram.ext.JobQueue``.
+
+To install multiple optional dependencies, separate them by commas, e.g. ``pip install python-telegram-bot[socks,webhooks]``.
+
+Additionally, two shortcuts are provided:
+
+* ``pip install python-telegram-bot[all]`` installs all optional dependencies.
+* ``pip install python-telegram-bot[ext]`` installs all optional dependencies that are related to ``telegram.ext``, i.e. ``[rate-limiter, webhooks, callback-data, job-queue]``.
 
 Quick Start
 ===========
@@ -149,10 +158,10 @@ Moreover, the `Tutorial: Your first Bot <https://github.com/python-telegram-bot/
 Resources
 =========
 
-- The `package documentation <https://python-telegram-bot.readthedocs.io/>`_ is the technical reference for ``python-telegram-bot``.
-  It contains descriptions of all available classes, modules, methods and arguments.
+- The `package documentation <https://docs.python-telegram-bot.org/>`_ is the technical reference for ``python-telegram-bot``.
+  It contains descriptions of all available classes, modules, methods and arguments as well as the `changelog <https://docs.python-telegram-bot.org/changelog.html>`_.
 - The `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ is home to number of more elaborate introductions of the different features of ``python-telegram-bot`` and other useful resources that go beyond the technical documentation.
-- Our `examples directory <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/README.md>`_ contains several examples that showcase the different features of both the Bot API and ``python-telegram-bot``.
+- Our `examples section <https://docs.python-telegram-bot.org/examples.html>`_ contains several examples that showcase the different features of both the Bot API and ``python-telegram-bot``.
   Even if it is not your approach for learning, please take a look at ``echobot.py``. It is the de facto base for most of the bots out there.
   The code for these examples is released to the public domain, so you can start by grabbing the code and building on top of it.
 - The `official Telegram Bot API documentation <https://core.telegram.org/bots/api>`_ is of course always worth a read.

README_RAW.rst

@@ -14,7 +14,7 @@
    :target: https://pypi.org/project/python-telegram-bot-raw/
    :alt: Supported Python versions
 
-.. image:: https://img.shields.io/badge/Bot%20API-6.0-blue?logo=telegram
+.. image:: https://img.shields.io/badge/Bot%20API-6.3-blue?logo=telegram
    :target: https://core.telegram.org/bots/api-changelog
    :alt: Supported Bot API versions
 
@@ -23,7 +23,7 @@
    :alt: PyPi Package Monthly Download
 
 .. image:: https://readthedocs.org/projects/python-telegram-bot/badge/?version=stable
-   :target: https://python-telegram-bot.readthedocs.io/
+   :target: https://docs.python-telegram-bot.org/
    :alt: Documentation Status
 
 .. image:: https://img.shields.io/pypi/l/python-telegram-bot-raw.svg
@@ -34,16 +34,16 @@
    :target: https://github.com/python-telegram-bot/python-telegram-bot/
    :alt: Github Actions workflow
 
-.. image:: https://codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg
-   :target: https://codecov.io/gh/python-telegram-bot/python-telegram-bot
+.. image:: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot
+   :target: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot
    :alt: Code coverage
 
-.. image:: http://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg
-   :target: http://isitmaintained.com/project/python-telegram-bot/python-telegram-bot
+.. image:: https://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg
+   :target: https://isitmaintained.com/project/python-telegram-bot/python-telegram-bot
    :alt: Median time to resolve an issue
 
 .. image:: https://api.codacy.com/project/badge/Grade/99d901eaa09b44b4819aec05c330c968
-   :target: https://www.codacy.com/app/python-telegram-bot/python-telegram-bot?utm_source=github.com&utm_medium=referral&utm_content=python-telegram-bot/python-telegram-bot&utm_campaign=Badge_Grade
+   :target: https://app.codacy.com/gh/python-telegram-bot/python-telegram-bot/dashboard
    :alt: Code quality: Codacy
 
 .. image:: https://deepsource.io/gh/python-telegram-bot/python-telegram-bot.svg/?label=active+issues
@@ -89,7 +89,7 @@ Installing both ``python-telegram-bot`` and ``python-telegram-bot-raw`` in conju
 Telegram API support
 ====================
 
-All types and methods of the Telegram Bot API **6.0** are supported.
+All types and methods of the Telegram Bot API **6.2** are supported.
 
 Installing
 ==========
@@ -120,23 +120,28 @@ Dependencies & Their Versions
 
 ``python-telegram-bot`` tries to use as few 3rd party dependencies as possible.
 However, for some features using a 3rd party library is more sane than implementing the functionality again.
-The dependencies are:
+As these features are *optional*, the corresponding 3rd party dependencies are not installed by default.
+Instead, they are listed as optional dependencies.
+This allows to avoid unnecessary dependency conflicts for users who don't need the optional features.
 
-* `httpx ~= 0.22.0 <https://www.python-httpx.org>`_ for ``telegram.request.HTTPXRequest``, the default networking backend
+The only required dependency is `httpx ~= 0.23.0 <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.
-To minimize dependency conflicts, we try to be liberal in terms of version requirements on the dependencies.
+To minimize dependency conflicts, we try to be liberal in terms of version requirements on the (optional) dependencies.
 On the other hand, we have to ensure stability of ``python-telegram-bot``, which is why we do apply version bounds.
 If you encounter dependency conflicts due to these bounds, feel free to reach out.
 
 Optional Dependencies
----------------------
+#####################
 
-``python-telegram-bot-raw`` can be installed with optional dependencies:
+PTB can be installed with optional dependencies:
 
-* ``pip install python-telegram-bot[passport]`` installs the `cryptography <https://cryptography.io>`_ library. Use this, if you want to use Telegram Passport related functionality.
-* ``pip install python-telegram-bot[json]`` installs the `ujson <https://pypi.org/project/ujson/>`_ library. It will then be used for JSON de- & encoding, which can bring speed up compared to the standard `json <https://docs.python.org/3/library/json.html>`_ library.
-* ``pip install python-telegram-bot[socks]`` installs the `PySocks <https://pypi.org/project/PySocks/>`_ library. Use this, if you want to work behind a Socks5 server.
+* ``pip install python-telegram-bot-raw[passport]`` installs the `cryptography>=3.0 <https://cryptography.io/en/stable>`_ library. Use this, if you want to use Telegram Passport related functionality.
+* ``pip install python-telegram-bot-raw[socks]`` installs ``httpx[socks]``. Use this, if you want to work behind a Socks5 server.
+
+To install multiple optional dependencies, separate them by commas, e.g. ``pip install python-telegram-bot-raw[passport,socks]``.
+
+Additionally, the shortcut ``pip install python-telegram-bot-raw[all]`` installs all optional dependencies.
 
 Quick Start
 ===========
@@ -146,10 +151,10 @@ Our Wiki contains an `Introduction to the API <https://github.com/python-telegra
 Resources
 =========
 
-- The `package documentation <https://python-telegram-bot.readthedocs.io/>`_ is the technical reference for ``python-telegram-bot``.
-  It contains descriptions of all available classes, modules, methods and arguments.
+- The `package documentation <https://docs.python-telegram-bot.org/>`_ is the technical reference for ``python-telegram-bot``.
+  It contains descriptions of all available classes, modules, methods and arguments as well as the `changelog <https://docs.python-telegram-bot.org/changelog.html>`_.
 - The `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ is home to number of more elaborate introductions of the different features of ``python-telegram-bot`` and other useful resources that go beyond the technical documentation.
-- Our `examples directory <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/README.md>`_ contains several examples that showcase the different features of both the Bot API and ``python-telegram-bot``.
+- Our `examples section <https://docs.python-telegram-bot.org/examples.html>`_ contains several examples that showcase the different features of both the Bot API and ``python-telegram-bot``.
   Even if it is not your approach for learning, please take a look at ``echobot.py``. It is the de facto base for most of the bots out there.
   The code for these examples is released to the public domain, so you can start by grabbing the code and building on top of it.
 - The `official Telegram Bot API documentation <https://core.telegram.org/bots/api>`_ is of course always worth a read.

docs/requirements-docs.txt

@@ -1,7 +1,6 @@
-sphinx==4.5.0
+sphinx==5.3.0
 sphinx-pypi-upload
-furo==2022.04.07
-# Can be replaced with a sphinx-paramlinks==... dependency once a version is released that
-# includes the commit mentioned below and maybe even
-# https://github.com/sqlalchemyorg/sphinx-paramlinks/pull/14
-git+https://github.com/sqlalchemyorg/sphinx-paramlinks.git@acedb03149e3f87ff599174b033754c2f58f1c95
+furo==2022.12.7
+git+https://github.com/harshil21/furo-sphinx-search@be5cfa221a01f6e259bb2bb1f76d6ede7ffc1f11#egg=furo-sphinx-search
+sphinx-paramlinks==0.5.4
+sphinxcontrib-mermaid==0.7.1

docs/source/_static/style_mermaid_diagrams.css

@@ -0,0 +1,3 @@
+.mermaid svg {
+  height: auto;
+}

docs/source/conf.py

@@ -1,16 +1,3 @@
-# -*- coding: utf-8 -*-
-#
-# Python Telegram Bot documentation build configuration file, created by
-# sphinx-quickstart on Mon Aug 10 22:25:07 2015.
-#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
 import inspect
 import os
 import re
@@ -18,7 +5,7 @@ import subprocess
 import sys
 from enum import Enum
 from pathlib import Path
-from typing import Tuple
+from typing import List, Tuple
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -32,9 +19,22 @@ from sphinx.util import logging
 sys.path.insert(0, os.path.abspath("../.."))
 
 # -- General configuration ------------------------------------------------
+# General information about the project.
+project = "python-telegram-bot"
+copyright = "2015-2022, Leandro Toledo"
+author = "Leandro Toledo"
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = "20.0b0"  # telegram.__version__[:3]
+# The full version, including alpha/beta/rc tags.
+release = "20.0b0"  # telegram.__version__
 
 # If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = "4.5.0"
+needs_sphinx = "5.1.1"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -45,6 +45,8 @@ extensions = [
     "sphinx.ext.intersphinx",
     "sphinx.ext.linkcode",
     "sphinx_paramlinks",
+    "sphinxcontrib.mermaid",
+    "sphinx_search.extension",
 ]
 
 # Use intersphinx to reference the python builtin library docs
@@ -53,76 +55,52 @@ intersphinx_mapping = {
     "APScheduler": ("https://apscheduler.readthedocs.io/en/3.x/", None),
 }
 
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+source_suffix = ".rst"
+
+# The master toctree document.
+master_doc = "index"
+
+# Global substitutions
+rst_prolog = (Path.cwd() / "../substitutions/global.rst").read_text(encoding="utf-8")
+
+# -- Extension settings ------------------------------------------------
+napoleon_use_admonition_for_examples = True
+
 # Don't show type hints in the signature - that just makes it hardly readable
 # and we document the types anyway
 autodoc_typehints = "none"
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
 # Fail on warnings & unresolved references etc
 nitpicky = True
 
 # Paramlink style
 paramlinks_hyperlink_param = "name"
 
+# Linkcheck settings
+linkcheck_ignore = [
+    # Let's not check issue/PR links - that's wasted resources
+    r"http(s)://github\.com/python-telegram-bot/python-telegram-bot/(issues|pull)/\d+/?",
+    # For some reason linkcheck has a problem with these two:
+    re.escape("https://github.com/python-telegram-bot/python-telegram-bot/discussions/new"),
+    re.escape("https://github.com/python-telegram-bot/python-telegram-bot/issues/new"),
+    # Anchors are apparently inserted by GitHub dynamically, so let's skip checking them
+    "https://github.com/python-telegram-bot/python-telegram-bot/tree/master/examples#",
+    r"https://github\.com/python-telegram-bot/python-telegram-bot/wiki/[\w\-_,]+\#",
+]
+linkcheck_allowed_redirects = {
+    # Redirects to the default version are okay
+    r"https://docs\.python-telegram-bot\.org/.*": r"https://docs\.python-telegram-bot\.org/en/[\w\d\.]+/.*",
+    # pre-commit.ci always redirects to the latest run
+    re.escape(
+        "https://results.pre-commit.ci/latest/github/python-telegram-bot/python-telegram-bot/master"
+    ): r"https://results\.pre-commit\.ci/run/github/.*",
+}
 
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-# source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
-
-# The encoding of source files.
-# source_encoding = 'utf-8-sig'
-
-# The master toctree document.
-master_doc = "index"
-
-# General information about the project.
-project = "python-telegram-bot"
-copyright = "2015-2021, Leandro Toledo"
-author = "Leandro Toledo"
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = "20.0a0"  # telegram.__version__[:3]
-# The full version, including alpha/beta/rc tags.
-release = "20.0a0"  # telegram.__version__
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-# today = ''
-# Else, today_fmt is used as the format for a strftime call.
-# today_fmt = '%B %d, %Y'
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-exclude_patterns = []
-
-# The reST default role (used for this markup: `text`) to use for all
-# documents.
-# default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-# add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-# add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-# show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
@@ -130,16 +108,9 @@ pygments_style = "sphinx"
 # Decides the language used for syntax highlighting of code blocks.
 highlight_language = "python3"
 
-# A list of ignored prefixes for module index sorting.
-# modindex_common_prefix = []
-
-# If true, keep warnings as "system message" paragraphs in the built documents.
-# keep_warnings = False
-
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
-
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -228,16 +199,10 @@ html_theme_options = {
     ],
 }
 
-# Add any paths that contain custom themes here, relative to this directory.
-# html_theme_path = []
-
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 html_title = f"python-telegram-bot<br> v{version}"
 
-# A shorter title for the navigation bar.  Default is the same as html_title.
-# html_short_title = None
-
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 html_logo = "ptb-logo_1024.png"
@@ -251,72 +216,17 @@ html_favicon = "ptb-logo_1024.ico"
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
+html_css_files = ["style_external_link.css", "style_mermaid_diagrams.css"]
 
-html_css_files = ["style_external_link.css"]
-
-# Add any extra paths that contain custom files (such as robots.txt or
-# .htaccess) here, relative to this directory. These files are copied
-# directly to the root of the documentation.
-# html_extra_path = []
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-# html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-# html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-# html_additional_pages = {}
-
-# If false, no module index is generated.
-# html_domain_indices = True
-
-# If false, no index is generated.
-# html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-# html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-# html_show_sourcelink = True
-
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-# html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-# html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
-# html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-# html_file_suffix = None
-
-# Language to be used for generating the HTML full-text search index.
-# Sphinx supports the following languages:
-#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
-#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
-# html_search_language = 'en'
-
-# A dictionary with options for the search language support, empty by default.
-# Now only 'ja' uses this config value
-# html_search_options = {'type': 'default'}
-
-# The name of a javascript file (relative to the configuration directory) that
-# implements a search results scorer. If empty, the default will be used.
-# html_search_scorer = 'scorer.js'
+html_permalinks_icon = "¶"  # Furo's default permalink icon is `#` which doesn't look great imo.
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = "python-telegram-bot-doc"
 
+# The base URL which points to the root of the HTML documentation. It is used to indicate the
+# location of document using The Canonical Link Relation. Default: ''.
+html_baseurl = "https://docs.python-telegram-bot.org"
+
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
@@ -343,32 +253,13 @@ latex_documents = [
 # the title page.
 latex_logo = "ptb-logo_1024.png"
 
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-# latex_use_parts = False
-
-# If true, show page references after internal links.
-# latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-# latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-# latex_appendices = []
-
-# If false, no module index is generated.
-# latex_domain_indices = True
-
-
 # -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [(master_doc, "python-telegram-bot", "python-telegram-bot Documentation", [author], 1)]
 
-# If true, show URL addresses after external links.
-# man_show_urls = False
-
+# rtd_sphinx_search_file_type = "un-minified"  # Configuration for furo-sphinx-search
 
 # -- Options for Texinfo output -------------------------------------------
 
@@ -387,22 +278,6 @@ texinfo_documents = [
     ),
 ]
 
-# Documents to append as an appendix to all manuals.
-# texinfo_appendices = []
-
-# If false, no module index is generated.
-# texinfo_domain_indices = True
-
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-# texinfo_show_urls = 'footnote'
-
-# If true, do not generate a @detailmenu in the "Top" node's menu.
-# texinfo_no_detailmenu = False
-
-# Napoleon stuff
-
-napoleon_use_admonition_for_examples = True
-
 # -- script stuff --------------------------------------------------------
 
 # get the sphinx(!) logger
@@ -420,7 +295,7 @@ class TGConstXRefRole(PyXRefRole):
 
     Example:
 
-        :tg-const:`telegram.constants.MessageLimit.TEXT_LENGTH` renders as `4096` but links to the
+        :tg-const:`telegram.constants.MessageLimit.MAX_TEXT_LENGTH` renders as `4096` but links to the
         constant.
     """
 
@@ -444,9 +319,17 @@ class TGConstXRefRole(PyXRefRole):
                 if isinstance(value, telegram.constants.FileSizeLimit):
                     return f"{int(value.value / 1e6)} MB", target
                 return repr(value.value), target
-            # Just for Bot API version number auto add in constants:
-            if isinstance(value, str) and target == "telegram.constants.BOT_API_VERSION":
+            # Just for (Bot API) versions number auto add in constants:
+            if isinstance(value, str) and target in (
+                "telegram.constants.BOT_API_VERSION",
+                "telegram.__version__",
+            ):
                 return value, target
+            if isinstance(value, tuple) and target in (
+                "telegram.constants.BOT_API_VERSION_INFO",
+                "telegram.__version_info__",
+            ):
+                return repr(value), target
             sphinx_logger.warning(
                 f"%s:%d: WARNING: Did not convert reference %s. :{CONSTANTS_ROLE}: is not supposed"
                 " to be used with this type of target.",
@@ -495,12 +378,98 @@ line_numbers = {}
 file_root = Path(inspect.getsourcefile(telegram)).parent.parent.resolve()
 import telegram.ext  # Needed for checking if an object is a BaseFilter
 
+keyword_args = [
+    ":keyword _sphinx_paramlinks_telegram.Bot.{method}.read_timeout: Value to pass to :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to {read_timeout}.",
+    ":kwtype _sphinx_paramlinks_telegram.Bot.{method}.read_timeout: {read_timeout_type}, optional",
+    ":keyword _sphinx_paramlinks_telegram.Bot.{method}.write_timeout: Value to pass to :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to {write_timeout}.",
+    ":kwtype _sphinx_paramlinks_telegram.Bot.{method}.write_timeout: :obj:`float` | :obj:`None`, optional",
+    ":keyword _sphinx_paramlinks_telegram.Bot.{method}.connect_timeout: Value to pass to :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.",
+    ":kwtype _sphinx_paramlinks_telegram.Bot.{method}.connect_timeout: :obj:`float` | :obj:`None`, optional",
+    ":keyword _sphinx_paramlinks_telegram.Bot.{method}.pool_timeout: Value to pass to :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.",
+    ":kwtype _sphinx_paramlinks_telegram.Bot.{method}.pool_timeout: :obj:`float` | :obj:`None`, optional",
+    ":keyword _sphinx_paramlinks_telegram.Bot.{method}.api_kwargs: Arbitrary keyword arguments to be passed to the Telegram API.",
+    ":kwtype _sphinx_paramlinks_telegram.Bot.{method}.api_kwargs: :obj:`dict`, optional",
+    "",
+]
 
-def autodoc_process_docstring(app: Sphinx, what, name: str, obj: object, options, lines):
-    """We misuse this autodoc hook to get the file names & line numbers because we have access
-    to the actual object here.
+write_timeout_sub = [":attr:`~telegram.request.BaseRequest.DEFAULT_NONE`", "``20``"]
+read_timeout_sub = [
+    ":attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.",
+    "``2``. :paramref:`timeout` will be added to this value",
+]
+read_timeout_type = [":obj:`float` | :obj:`None`", ":obj:`float`"]
+
+
+def find_insert_pos(lines: List[str]) -> int:
+    """Finds the correct position to insert the keyword arguments and returns the index."""
+    for idx, value in reversed(list(enumerate(lines))):  # reversed since :returns: is at the end
+        if value.startswith(":returns:"):
+            return idx
+    else:
+        return False
+
+
+def is_write_timeout_20(obj: object) -> int:
+    """inspects the default value of write_timeout parameter of the bot method."""
+    sig = inspect.signature(obj)
+    return 1 if (sig.parameters["write_timeout"].default == 20) else 0
+
+
+def check_timeout_and_api_kwargs_presence(obj: object) -> int:
+    """Checks if the method has timeout and api_kwargs keyword only parameters."""
+    sig = inspect.signature(obj)
+    params_to_check = (
+        "read_timeout",
+        "write_timeout",
+        "connect_timeout",
+        "pool_timeout",
+        "api_kwargs",
+    )
+    return all(
+        param in sig.parameters and sig.parameters[param].kind == inspect.Parameter.KEYWORD_ONLY
+        for param in params_to_check
+    )
+
+
+def autodoc_process_docstring(
+    app: Sphinx, what, name: str, obj: object, options, lines: List[str]
+):
+    """We do two things:
+    1) Use this method to automatically insert the Keyword Args for the Bot methods.
+
+    2) Misuse this autodoc hook to get the file names & line numbers because we have access
+       to the actual object here.
     """
-    # Ce can't properly handle ordinary attributes.
+    # 1) Insert the Keyword Args for the Bot methods
+    method_name = name.split(".")[-1]
+    if (
+        name.startswith("telegram.Bot.")
+        and what == "method"
+        and method_name.islower()
+        and check_timeout_and_api_kwargs_presence(obj)
+    ):
+        insert_index = find_insert_pos(lines)
+        if not insert_index:
+            raise ValueError(
+                f"Couldn't find the correct position to insert the keyword args for {obj}."
+            )
+
+        long_write_timeout = is_write_timeout_20(obj)
+        get_updates_sub = 1 if (method_name == "get_updates") else 0
+        # The below can be done in 1 line with itertools.chain, but this must be modified in-place
+        for i in range(insert_index, insert_index + len(keyword_args)):
+            lines.insert(
+                i,
+                keyword_args[i - insert_index].format(
+                    method=method_name,
+                    write_timeout=write_timeout_sub[long_write_timeout],
+                    read_timeout=read_timeout_sub[get_updates_sub],
+                    read_timeout_type=read_timeout_type[get_updates_sub],
+                ),
+            )
+
+    # 2) Get the file names & line numbers
+    # We can't properly handle ordinary attributes.
     # In linkcode_resolve we'll resolve to the `__init__` or module instead
     if what == "attribute":
         return
@@ -598,6 +567,10 @@ def autodoc_process_bases(app, name, obj, option, bases: list):
             bases.insert(0, ":class:`str`")
             continue
 
+        if "IntEnum" in base:
+            bases[idx] = ":class:`enum.IntEnum`"
+            continue
+
         # Drop generics (at least for now)
         if base.endswith("]"):
             base = base.split("[", maxsplit=1)[0]
@@ -606,7 +579,7 @@ def autodoc_process_bases(app, name, obj, option, bases: list):
         # Now convert `telegram._message.Message` to `telegram.Message` etc
         match = re.search(pattern=r"(telegram(\.ext|))\.[_\w\.]+", string=base)
         if not match or "_utils" in base:
-            return
+            continue
 
         parts = match.group(0).split(".")
 

docs/source/examples.arbitrarycallbackdatabot.rst

@@ -0,0 +1,7 @@
+``arbitrarycallbackdatabot.py``
+===============================
+
+.. literalinclude:: ../../examples/arbitrarycallbackdatabot.py
+   :language: python
+   :linenos:
+    

docs/source/examples.chatmemberbot.rst

@@ -0,0 +1,7 @@
+``chatmemberbot.py``
+====================
+
+.. literalinclude:: ../../examples/chatmemberbot.py
+   :language: python
+   :linenos:
+    

docs/source/examples.contexttypesbot.rst

@@ -0,0 +1,7 @@
+``contexttypesbot.py``
+======================
+
+.. literalinclude:: ../../examples/contexttypesbot.py
+   :language: python
+   :linenos:
+    

docs/source/examples.conversationbot.rst

@@ -0,0 +1,13 @@
+``conversationbot.py``
+======================
+
+.. literalinclude:: ../../examples/conversationbot.py
+   :language: python
+   :linenos:
+
+.. _conversationbot-diagram:
+
+State Diagram
+-------------
+
+.. mermaid:: ../../examples/conversationbot.mmd

docs/source/examples.conversationbot2.rst

@@ -0,0 +1,13 @@
+``conversationbot2.py``
+=======================
+
+.. literalinclude:: ../../examples/conversationbot2.py
+   :language: python
+   :linenos:
+
+.. _conversationbot2-diagram:
+
+State Diagram
+-------------
+
+.. mermaid:: ../../examples/conversationbot2.mmd

docs/source/examples.customwebhookbot.rst

@@ -0,0 +1,7 @@
+``customwebhookbot.py``
+=======================
+
+.. literalinclude:: ../../examples/customwebhookbot.py
+   :language: python
+   :linenos:
+    

docs/source/examples.deeplinking.rst

@@ -0,0 +1,7 @@
+``deeplinking.py``
+==================
+
+.. literalinclude:: ../../examples/deeplinking.py
+   :language: python
+   :linenos:
+    

docs/source/examples.echobot.rst

@@ -0,0 +1,7 @@
+``echobot.py``
+==============
+
+.. literalinclude:: ../../examples/echobot.py
+   :language: python
+   :linenos:
+    

docs/source/examples.errorhandlerbot.rst

@@ -0,0 +1,7 @@
+``errorhandlerbot.py``
+======================
+
+.. literalinclude:: ../../examples/errorhandlerbot.py
+   :language: python
+   :linenos:
+    

docs/source/examples.inlinebot.rst

@@ -0,0 +1,7 @@
+``inlinebot.py``
+================
+
+.. literalinclude:: ../../examples/inlinebot.py
+   :language: python
+   :linenos:
+    

docs/source/examples.inlinekeyboard.rst

@@ -0,0 +1,7 @@
+``inlinekeyboard.py``
+=====================
+
+.. literalinclude:: ../../examples/inlinekeyboard.py
+   :language: python
+   :linenos:
+    

docs/source/examples.inlinekeyboard2.rst

@@ -0,0 +1,7 @@
+``inlinekeyboard2.py``
+======================
+
+.. literalinclude:: ../../examples/inlinekeyboard2.py
+   :language: python
+   :linenos:
+    

docs/source/examples.nestedconversationbot.rst

@@ -0,0 +1,13 @@
+``nestedconversationbot.py``
+============================
+
+.. literalinclude:: ../../examples/nestedconversationbot.py
+   :language: python
+   :linenos:
+
+.. _nestedconversationbot-diagram:
+
+State Diagram
+-------------
+
+.. mermaid:: ../../examples/nestedconversationbot.mmd

docs/source/examples.passportbot.rst

@@ -0,0 +1,16 @@
+``passportbot.py``
+==================
+
+.. literalinclude:: ../../examples/passportbot.py
+   :language: python
+   :linenos:
+
+.. _passportbot-html:
+
+HTML Page
+---------
+
+.. literalinclude:: ../../examples/passportbot.html
+   :language: html
+   :linenos:
+    

docs/source/examples.paymentbot.rst

@@ -0,0 +1,7 @@
+``paymentbot.py``
+=================
+
+.. literalinclude:: ../../examples/paymentbot.py
+   :language: python
+   :linenos:
+    

docs/source/examples.persistentconversationbot.rst

@@ -0,0 +1,7 @@
+``persistentconversationbot.py``
+================================
+
+.. literalinclude:: ../../examples/persistentconversationbot.py
+   :language: python
+   :linenos:
+    

docs/source/examples.pollbot.rst

@@ -0,0 +1,7 @@
+``pollbot.py``
+==============
+
+.. literalinclude:: ../../examples/pollbot.py
+   :language: python
+   :linenos:
+    

docs/source/examples.rawapibot.rst

@@ -0,0 +1,11 @@
+`rawapibot.py`
+==============
+
+This example uses only the pure, "bare-metal" API wrapper.
+
+
+
+.. literalinclude:: ../../examples/rawapibot.py
+   :language: python
+   :linenos:
+    

docs/source/examples.rst

@@ -0,0 +1,197 @@
+Examples
+========
+
+In this section we display small examples to show what a bot written with
+``python-telegram-bot`` looks like.
+Some bots focus on one specific
+aspect of the Telegram Bot API while others focus on one of the
+mechanics of this library. Except for the
+:any:`examples.rawapibot` example, they all use the high-level
+framework this library provides with the
+:any:`telegram.ext <telegram.ext>` submodule.
+
+All examples are licensed under the `CC0
+License <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/LICENSE.txt>`__
+and are therefore fully dedicated to the public domain. You can use them
+as the base for your own bots without worrying about copyrights.
+
+Do note that we ignore one pythonic convention. Best practice would
+dictate, in many handler callbacks function signatures, to replace the
+argument ``context`` with an underscore, since ``context`` is an unused
+local variable in those callbacks. However, since these are examples and
+not having a name for that argument confuses beginners, we decided to
+have it present.
+
+:any:`examples.echobot`
+-----------------------
+
+This is probably the base for most of the bots made with
+``python-telegram-bot``. It simply replies to each text message with a
+message that contains the same text.
+
+:any:`examples.timerbot`
+------------------------
+
+This bot uses the
+:class:`telegram.ext.JobQueue`
+class to send timed messages. The user sets a timer by using ``/set``
+command with a specific time, for example ``/set 30``. The bot then sets
+up a job to send a message to that user after 30 seconds. The user can
+also cancel the timer by sending ``/unset``. To learn more about the
+``JobQueue``, read `this wiki
+article <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions-%E2%80%93-JobQueue>`__.
+Note: To use ``JobQueue``, you must install PTB via ``pip install python-telegram-bot[job-queue]``
+
+:any:`examples.conversationbot`
+-------------------------------
+
+A common task for a bot is to ask information from the user. In v5.0 of
+this library, we introduced the
+:class:`telegram.ext.ConversationHandler`
+for that exact purpose. This example uses it to retrieve
+user-information in a conversation-like style. To get a better
+understanding, take a look at the :ref:`state diagram <conversationbot-diagram>`.
+
+:any:`examples.conversationbot2`
+--------------------------------
+
+A more complex example of a bot that uses the ``ConversationHandler``.
+It is also more confusing. Good thing there is a :ref:`fancy state diagram <conversationbot2-diagram>`.
+for this one, too!
+
+:any:`examples.nestedconversationbot`
+-------------------------------------
+
+A even more complex example of a bot that uses the nested
+``ConversationHandler``\ s. While it’s certainly not that complex that
+you couldn’t built it without nested ``ConversationHanldler``\ s, it
+gives a good impression on how to work with them. Of course, there is a
+:ref:`fancy state diagram <nestedconversationbot-diagram>`
+for this example, too!
+
+:any:`examples.persistentconversationbot`
+-----------------------------------------
+
+A basic example of a bot store conversation state and user_data over
+multiple restarts.
+
+:any:`examples.inlinekeyboard`
+------------------------------
+
+This example sheds some light on inline keyboards, callback queries and
+message editing. A wiki site explaining this examples lives
+`here <https://github.com/python-telegram-bot/python-telegram-bot/wiki/InlineKeyboard-Example>`__.
+
+:any:`examples.inlinekeyboard2`
+-------------------------------
+
+A more complex example about inline keyboards, callback queries and
+message editing. This example showcases how an interactive menu could be
+build using inline keyboards.
+
+:any:`examples.deeplinking`
+---------------------------
+
+A basic example on how to use deeplinking with inline keyboards.
+
+:any:`examples.inlinebot`
+-------------------------
+
+A basic example of an `inline
+bot <https://core.telegram.org/bots/inline>`__. Don’t forget to enable
+inline mode with `@BotFather <https://telegram.me/BotFather>`_.
+
+:any:`examples.pollbot`
+-----------------------
+
+This example sheds some light on polls, poll answers and the
+corresponding handlers.
+
+:any:`examples.passportbot`
+---------------------------
+
+A basic example of a bot that can accept passports. Use in combination
+with the :ref:`HTML page <passportbot-html>`.
+Don’t forget to enable and configure payments with
+`@BotFather <https://telegram.me/BotFather>`_. Check out this
+`guide <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Telegram-Passport>`__
+on Telegram passports in PTB.
+Note: To use Telegram Passport, you must install PTB via ``pip install python-telegram-bot[passport]``
+
+:any:`examples.paymentbot`
+--------------------------
+
+A basic example of a bot that can accept payments. Don’t forget to
+enable and configure payments with
+`@BotFather <https://telegram.me/BotFather>`_.
+
+:any:`examples.errorhandlerbot`
+-------------------------------
+
+A basic example on how to set up a custom error handler.
+
+:any:`examples.chatmemberbot`
+-----------------------------
+
+A basic example on how ``(my_)chat_member`` updates can be used.
+
+:any:`examples.webappbot`
+-------------------------
+
+A basic example of how `Telegram
+WebApps <https://core.telegram.org/bots/webapps>`__ can be used. Use in
+combination with the :ref:`HTML page <webappbot-html>`.
+For your convenience, this file is hosted by the PTB team such that you
+don’t need to host it yourself. Uses the
+`iro.js <https://iro.js.org>`__ JavaScript library to showcase a
+user interface that is hard to achieve with native Telegram
+functionality.
+
+:any:`examples.contexttypesbot`
+-------------------------------
+
+This example showcases how ``telegram.ext.ContextTypes`` can be used to
+customize the ``context`` argument of handler and job callbacks.
+
+:any:`examples.customwebhookbot`
+--------------------------------
+
+This example showcases how a custom webhook setup can be used in
+combination with ``telegram.ext.Application``.
+
+:any:`examples.arbitrarycallbackdatabot`
+----------------------------------------
+
+This example showcases how PTBs “arbitrary callback data” feature can be
+used.
+Note: To use arbitrary callback data, you must install PTB via ``pip install python-telegram-bot[callback-data]``
+
+Pure API
+--------
+
+The :any:`examples.rawapibot` example example uses only the pure, “bare-metal” API wrapper.
+
+.. toctree::
+   :hidden:
+
+   examples.arbitrarycallbackdatabot
+   examples.chatmemberbot
+   examples.contexttypesbot
+   examples.conversationbot
+   examples.conversationbot2
+   examples.customwebhookbot
+   examples.deeplinking
+   examples.echobot
+   examples.errorhandlerbot
+   examples.inlinebot
+   examples.inlinekeyboard
+   examples.inlinekeyboard2
+   examples.nestedconversationbot
+   examples.passportbot
+   examples.paymentbot
+   examples.persistentconversationbot
+   examples.pollbot
+   examples.rawapibot
+   examples.timerbot
+   examples.webappbot
+

docs/source/examples.timerbot.rst

@@ -0,0 +1,7 @@
+``timerbot.py``
+===============
+
+.. literalinclude:: ../../examples/timerbot.py
+   :language: python
+   :linenos:
+    

docs/source/examples.webappbot.rst

@@ -0,0 +1,16 @@
+``webappbot.py``
+================
+
+.. literalinclude:: ../../examples/webappbot.py
+   :language: python
+   :linenos:
+
+.. _webappbot-html:
+
+HTML Page
+---------
+
+.. literalinclude:: ../../examples/webappbot.html
+   :language: html
+   :linenos:
+    

docs/source/inclusions/application_run_tip.rst

@@ -0,0 +1,7 @@
+.. tip::
+    When combining ``python-telegram-bot`` with other :mod:`asyncio` based frameworks, using this
+    method is likely not the best choice, as it blocks the event loop until it receives a stop
+    signal as described above.
+    Instead, you can manually call the methods listed below to start and shut down the application
+    and the :attr:`~telegram.ext.Application.updater`.
+    Keeping the event loop running and listening for a stop signal is then up to you.

docs/source/inclusions/bot_methods.rst

@@ -206,6 +206,8 @@
       - Used for getting a sticker set
     * - :meth:`~telegram.Bot.upload_sticker_file`
       - Used for uploading a sticker file
+    * - :meth:`~telegram.Bot.get_custom_emoji_stickers`
+      - Used for getting custom emoji files based on their IDs
 
 .. raw:: html
 
@@ -254,6 +256,35 @@
    </details>
    <br>
 
+.. raw:: html
+
+   <details>
+   <summary>Forum topic management</summary>
+
+.. list-table::
+    :align: left
+    :widths: 1 4
+
+    * - :meth:`~telegram.Bot.close_forum_topic`
+      - Used for closing a forum topic
+    * - :meth:`~telegram.Bot.create_forum_topic`
+      - Used to create a topic
+    * - :meth:`~telegram.Bot.delete_forum_topic`
+      - Used for deleting a forum topic
+    * - :meth:`~telegram.Bot.edit_forum_topic`
+      - Used to edit a topic
+    * - :meth:`~telegram.Bot.reopen_forum_topic`
+      - Used to reopen a topic
+    * - :meth:`~telegram.Bot.get_forum_topic_icon_stickers`
+      - Used to get custom emojis to use as topic icons
+    * - :meth:`~telegram.Bot.unpin_all_forum_topic_messages`
+      - Used to unpin all messages in a forum topic
+
+.. raw:: html
+
+   </details>
+   <br>
+
 .. raw:: html
 
    <details>
@@ -263,6 +294,8 @@
     :align: left
     :widths: 1 4
 
+    * - :meth:`~telegram.Bot.create_invoice_link`
+      - Used to generate an HTTP link for an invoice
     * - :meth:`~telegram.Bot.close`
       - Used for closing server instance when switching to another local server
     * - :meth:`~telegram.Bot.log_out`
@@ -286,6 +319,10 @@
     :align: left
     :widths: 1 4
 
+    * - :attr:`~telegram.Bot.base_file_url`
+      - Telegram Bot API file URL
+    * - :attr:`~telegram.Bot.base_url`
+      - Telegram Bot API service URL
     * - :attr:`~telegram.Bot.bot`
       - The user instance of the bot as returned by :meth:`~telegram.Bot.get_me`
     * - :attr:`~telegram.Bot.can_join_groups`
@@ -300,12 +337,18 @@
       - The first name of the bot
     * - :attr:`~telegram.Bot.last_name`
       - The last name of the bot
+    * - :attr:`~telegram.Bot.local_mode`
+      - Whether the bot is running in local mode
     * - :attr:`~telegram.Bot.username`
       - The username of the bot, without leading ``@``
     * - :attr:`~telegram.Bot.link`
       - The t.me link of the bot
+    * - :attr:`~telegram.Bot.private_key`
+      - Deserialized private key for decryption of telegram passport data
     * - :attr:`~telegram.Bot.supports_inline_queries`
       - Whether the bot supports inline queries
+    * - :attr:`~telegram.Bot.token`
+      - Bot's unique authentication token
 
 .. raw:: html
 

docs/source/inclusions/pool_size_tip.rst

@@ -0,0 +1,10 @@
+.. tip::
+    When making requests to the Bot API in an asynchronous fashion (e.g. via
+    :attr:`block=False <telegram.ext.BaseHandler.block>`, :meth:`Application.create_task <telegram.ext.Application.create_task>`,
+    :meth:`~telegram.ext.ApplicationBuilder.concurrent_updates` or the :class:`~telegram.ext.JobQueue`), it can happen that more requests
+    are being made in parallel than there are connections in the pool.
+    If the number of requests is much higher than the number of connections, even setting
+    :meth:`~telegram.ext.ApplicationBuilder.pool_timeout` to a larger value may not always be enough to prevent pool
+    timeouts.
+    You should therefore set :meth:`~telegram.ext.ApplicationBuilder.concurrent_updates`, :meth:`~telegram.ext.ApplicationBuilder.connection_pool_size` and
+    :meth:`~telegram.ext.ApplicationBuilder.pool_timeout` to values that make sense for your setup.

docs/source/index.rst

@@ -5,7 +5,7 @@
 
 .. include:: ../../README.rst
 
-.. The toctrees are hidden such that they don't reander on the start page but still include the contents into the documentation.
+.. The toctrees are hidden such that they don't render on the start page but still include the contents into the documentation.
 
 .. toctree::
    :hidden:
@@ -16,6 +16,13 @@
    telegram_auxil
    Telegrams Bot API Docs <https://core.telegram.org/bots/api>
 
+.. toctree::
+   :hidden:
+   :caption: Resources
+
+   examples
+   Wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki>
+
 .. toctree::
    :hidden:
    :caption: Project

docs/source/telegram.at-tree.rst

@@ -0,0 +1,87 @@
+Available Types
+---------------
+
+.. toctree::
+    :titlesonly:
+
+    telegram.animation
+    telegram.audio
+    telegram.botcommand
+    telegram.botcommandscope
+    telegram.botcommandscopeallchatadministrators
+    telegram.botcommandscopeallgroupchats
+    telegram.botcommandscopeallprivatechats
+    telegram.botcommandscopechat
+    telegram.botcommandscopechatadministrators
+    telegram.botcommandscopechatmember
+    telegram.botcommandscopedefault
+    telegram.callbackquery
+    telegram.chat
+    telegram.chatadministratorrights
+    telegram.chatinvitelink
+    telegram.chatjoinrequest
+    telegram.chatlocation
+    telegram.chatmember
+    telegram.chatmemberadministrator
+    telegram.chatmemberbanned
+    telegram.chatmemberleft
+    telegram.chatmembermember
+    telegram.chatmemberowner
+    telegram.chatmemberrestricted
+    telegram.chatmemberupdated
+    telegram.chatpermissions
+    telegram.chatphoto
+    telegram.contact
+    telegram.dice
+    telegram.document
+    telegram.file
+    telegram.forcereply
+    telegram.forumtopic
+    telegram.forumtopicclosed
+    telegram.forumtopiccreated
+    telegram.forumtopicreopened
+    telegram.inlinekeyboardbutton
+    telegram.inlinekeyboardmarkup
+    telegram.inputfile
+    telegram.inputmedia
+    telegram.inputmediaanimation
+    telegram.inputmediaaudio
+    telegram.inputmediadocument
+    telegram.inputmediaphoto
+    telegram.inputmediavideo
+    telegram.keyboardbutton
+    telegram.keyboardbuttonpolltype
+    telegram.location
+    telegram.loginurl
+    telegram.menubutton
+    telegram.menubuttoncommands
+    telegram.menubuttondefault
+    telegram.menubuttonwebapp
+    telegram.message
+    telegram.messageautodeletetimerchanged
+    telegram.messageentity
+    telegram.messageid
+    telegram.photosize
+    telegram.poll
+    telegram.pollanswer
+    telegram.polloption
+    telegram.proximityalerttriggered
+    telegram.replykeyboardmarkup
+    telegram.replykeyboardremove
+    telegram.sentwebappmessage
+    telegram.telegramobject
+    telegram.update
+    telegram.user
+    telegram.userprofilephotos
+    telegram.venue
+    telegram.video
+    telegram.videochatended
+    telegram.videochatparticipantsinvited
+    telegram.videochatscheduled
+    telegram.videochatstarted
+    telegram.videonote
+    telegram.voice
+    telegram.webappdata
+    telegram.webappinfo
+    telegram.webhookinfo
+

docs/source/telegram.dice.rst

@@ -3,4 +3,4 @@ telegram.Dice
 
 .. autoclass:: telegram.Dice
     :members:
-    :show-inheritance:
+    :show-inheritance:

docs/source/telegram.ext.acd-tree.rst

@@ -0,0 +1,8 @@
+Arbitrary Callback Data
+-----------------------
+
+.. toctree::
+    :titlesonly:
+
+    telegram.ext.callbackdatacache
+    telegram.ext.invalidcallbackdata

docs/source/telegram.ext.aioratelimiter.rst

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

docs/source/telegram.ext.basehandler.rst

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

docs/source/telegram.ext.baseratelimiter.rst

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

docs/source/telegram.ext.extbot.rst

@@ -3,5 +3,4 @@ telegram.ext.ExtBot
 
 .. autoclass:: telegram.ext.ExtBot
     :show-inheritance:
-
-    .. autofunction:: telegram.ext.ExtBot.insert_callback_data
+    :members: insert_callback_data, defaults, rate_limiter, initialize, shutdown, callback_data_cache

docs/source/telegram.ext.handler.rst

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

docs/source/telegram.ext.handlers-tree.rst

@@ -0,0 +1,24 @@
+Handlers
+--------
+
+.. toctree::
+    :titlesonly:
+
+    telegram.ext.basehandler
+    telegram.ext.callbackqueryhandler
+    telegram.ext.chatjoinrequesthandler
+    telegram.ext.chatmemberhandler
+    telegram.ext.choseninlineresulthandler
+    telegram.ext.commandhandler
+    telegram.ext.conversationhandler
+    telegram.ext.filters
+    telegram.ext.inlinequeryhandler
+    telegram.ext.messagehandler
+    telegram.ext.pollanswerhandler
+    telegram.ext.pollhandler
+    telegram.ext.precheckoutqueryhandler
+    telegram.ext.prefixhandler
+    telegram.ext.shippingqueryhandler
+    telegram.ext.stringcommandhandler
+    telegram.ext.stringregexhandler
+    telegram.ext.typehandler

docs/source/telegram.ext.persistence-tree.rst

@@ -0,0 +1,10 @@
+Persistence
+-----------
+
+.. toctree::
+    :titlesonly:
+
+    telegram.ext.basepersistence
+    telegram.ext.dictpersistence
+    telegram.ext.persistenceinput
+    telegram.ext.picklepersistence

docs/source/telegram.ext.rate-limiting-tree.rst

@@ -0,0 +1,8 @@
+Rate Limiting
+-------------
+
+.. toctree::
+    :titlesonly:
+
+    telegram.ext.baseratelimiter
+    telegram.ext.aioratelimiter

docs/source/telegram.ext.rst

@@ -2,56 +2,19 @@ telegram.ext package
 ====================
 
 .. toctree::
+    :titlesonly:
 
-    telegram.ext.extbot
-    telegram.ext.applicationbuilder
     telegram.ext.application
+    telegram.ext.applicationbuilder
     telegram.ext.applicationhandlerstop
-    telegram.ext.updater
     telegram.ext.callbackcontext
-    telegram.ext.job
-    telegram.ext.jobqueue
     telegram.ext.contexttypes
     telegram.ext.defaults
-
-Handlers
---------
-
-.. toctree::
-
-    telegram.ext.handler
-    telegram.ext.callbackqueryhandler
-    telegram.ext.chatjoinrequesthandler
-    telegram.ext.chatmemberhandler
-    telegram.ext.choseninlineresulthandler
-    telegram.ext.commandhandler
-    telegram.ext.conversationhandler
-    telegram.ext.inlinequeryhandler
-    telegram.ext.messagehandler
-    telegram.ext.filters
-    telegram.ext.pollanswerhandler
-    telegram.ext.pollhandler
-    telegram.ext.precheckoutqueryhandler
-    telegram.ext.prefixhandler
-    telegram.ext.shippingqueryhandler
-    telegram.ext.stringcommandhandler
-    telegram.ext.stringregexhandler
-    telegram.ext.typehandler
-
-Persistence
------------
-
-.. toctree::
-
-    telegram.ext.basepersistence
-    telegram.ext.persistenceinput
-    telegram.ext.picklepersistence
-    telegram.ext.dictpersistence
-
-Arbitrary Callback Data
------------------------
-
-.. toctree::
-
-    telegram.ext.callbackdatacache
-    telegram.ext.invalidcallbackdata
+    telegram.ext.extbot
+    telegram.ext.job
+    telegram.ext.jobqueue
+    telegram.ext.updater
+    telegram.ext.handlers-tree.rst
+    telegram.ext.persistence-tree.rst
+    telegram.ext.acd-tree.rst
+    telegram.ext.rate-limiting-tree.rst

docs/source/telegram.forumtopic.rst

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

docs/source/telegram.forumtopicclosed.rst

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

docs/source/telegram.forumtopiccreated.rst

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

docs/source/telegram.forumtopicreopened.rst

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

docs/source/telegram.games-tree.rst

@@ -0,0 +1,9 @@
+Games
+-----
+
+.. toctree::
+    :titlesonly:
+
+    telegram.callbackgame
+    telegram.game
+    telegram.gamehighscore

docs/source/telegram.inline-tree.rst

@@ -0,0 +1,35 @@
+Inline Mode
+-----------
+
+.. toctree::
+    :titlesonly:
+
+    telegram.choseninlineresult
+    telegram.inlinequery
+    telegram.inlinequeryresult
+    telegram.inlinequeryresultarticle
+    telegram.inlinequeryresultaudio
+    telegram.inlinequeryresultcachedaudio
+    telegram.inlinequeryresultcacheddocument
+    telegram.inlinequeryresultcachedgif
+    telegram.inlinequeryresultcachedmpeg4gif
+    telegram.inlinequeryresultcachedphoto
+    telegram.inlinequeryresultcachedsticker
+    telegram.inlinequeryresultcachedvideo
+    telegram.inlinequeryresultcachedvoice
+    telegram.inlinequeryresultcontact
+    telegram.inlinequeryresultdocument
+    telegram.inlinequeryresultgame
+    telegram.inlinequeryresultgif
+    telegram.inlinequeryresultlocation
+    telegram.inlinequeryresultmpeg4gif
+    telegram.inlinequeryresultphoto
+    telegram.inlinequeryresultvenue
+    telegram.inlinequeryresultvideo
+    telegram.inlinequeryresultvoice
+    telegram.inputmessagecontent
+    telegram.inputtextmessagecontent
+    telegram.inputlocationmessagecontent
+    telegram.inputvenuemessagecontent
+    telegram.inputcontactmessagecontent
+    telegram.inputinvoicemessagecontent

docs/source/telegram.passport-tree.rst

@@ -0,0 +1,28 @@
+Passport
+--------
+
+.. toctree::
+    :titlesonly:
+
+    telegram.credentials
+    telegram.datacredentials
+    telegram.encryptedcredentials
+    telegram.encryptedpassportelement
+    telegram.filecredentials
+    telegram.iddocumentdata
+    telegram.passportdata
+    telegram.passportelementerror
+    telegram.passportelementerrordatafield
+    telegram.passportelementerrorfile
+    telegram.passportelementerrorfiles
+    telegram.passportelementerrorfrontside
+    telegram.passportelementerrorreverseside
+    telegram.passportelementerrorselfie
+    telegram.passportelementerrortranslationfile
+    telegram.passportelementerrortranslationfiles
+    telegram.passportelementerrorunspecified
+    telegram.passportfile
+    telegram.personaldetails
+    telegram.residentialaddress
+    telegram.securedata
+    telegram.securevalue

docs/source/telegram.payments-tree.rst

@@ -0,0 +1,14 @@
+Payments
+--------
+
+.. toctree::
+    :titlesonly:
+
+    telegram.invoice
+    telegram.labeledprice
+    telegram.orderinfo
+    telegram.precheckoutquery
+    telegram.shippingaddress
+    telegram.shippingoption
+    telegram.shippingquery
+    telegram.successfulpayment

docs/source/telegram.request.rst

@@ -4,6 +4,8 @@ telegram.request Module
 .. versionadded:: 20.0
 
 .. toctree::
+    :titlesonly:
+
     telegram.request.baserequest
     telegram.request.requestdata
     telegram.request.httpxrequest

docs/source/telegram.rst

@@ -1,177 +1,23 @@
 telegram package
 ================
 
-.. toctree::
+Version Constants
+-----------------
+
+.. automodule:: telegram
+   :members: __version__, __version_info__, __bot_api_version__, __bot_api_version_info__
+
+Classes in this package
+-----------------------
+
+.. toctree::
+    :titlesonly:
 
-    telegram.animation
-    telegram.audio
     telegram.bot
-    telegram.botcommand
-    telegram.botcommandscope
-    telegram.botcommandscopedefault
-    telegram.botcommandscopeallprivatechats
-    telegram.botcommandscopeallgroupchats
-    telegram.botcommandscopeallchatadministrators
-    telegram.botcommandscopechat
-    telegram.botcommandscopechatadministrators
-    telegram.botcommandscopechatmember
-    telegram.callbackquery
-    telegram.chat
-    telegram.chatadministratorrights
-    telegram.chatinvitelink
-    telegram.chatjoinrequest
-    telegram.chatlocation
-    telegram.chatmember
-    telegram.chatmemberowner
-    telegram.chatmemberadministrator
-    telegram.chatmembermember
-    telegram.chatmemberrestricted
-    telegram.chatmemberleft
-    telegram.chatmemberbanned
-    telegram.chatmemberupdated
-    telegram.chatpermissions
-    telegram.chatphoto
-    telegram.contact
-    telegram.dice
-    telegram.document
-    telegram.file
-    telegram.forcereply
-    telegram.inlinekeyboardbutton
-    telegram.inlinekeyboardmarkup
-    telegram.inputfile
-    telegram.inputmedia
-    telegram.inputmediaanimation
-    telegram.inputmediaaudio
-    telegram.inputmediadocument
-    telegram.inputmediaphoto
-    telegram.inputmediavideo
-    telegram.keyboardbutton
-    telegram.keyboardbuttonpolltype
-    telegram.location
-    telegram.loginurl
-    telegram.menubutton
-    telegram.menubuttoncommands
-    telegram.menubuttondefault
-    telegram.menubuttonwebapp
-    telegram.message
-    telegram.messageautodeletetimerchanged
-    telegram.messageid
-    telegram.messageentity
-    telegram.photosize
-    telegram.poll
-    telegram.pollanswer
-    telegram.polloption
-    telegram.proximityalerttriggered
-    telegram.replykeyboardremove
-    telegram.replykeyboardmarkup
-    telegram.sentwebappmessage
-    telegram.telegramobject
-    telegram.update
-    telegram.user
-    telegram.userprofilephotos
-    telegram.venue
-    telegram.video
-    telegram.videochatended
-    telegram.videochatparticipantsinvited
-    telegram.videochatscheduled
-    telegram.videochatstarted
-    telegram.videonote
-    telegram.voice
-    telegram.webappdata
-    telegram.webappinfo
-    telegram.webhookinfo
+    telegram.at-tree.rst
+    telegram.stickers-tree.rst
+    telegram.inline-tree.rst
+    telegram.payments-tree.rst
+    telegram.games-tree.rst
+    telegram.passport-tree.rst
 
-Stickers
---------
-
-.. toctree::
-
-    telegram.sticker
-    telegram.stickerset
-    telegram.maskposition
-
-Inline Mode
------------
-
-.. toctree::
-
-    telegram.inlinequery
-    telegram.inlinequeryresult
-    telegram.inlinequeryresultarticle
-    telegram.inlinequeryresultaudio
-    telegram.inlinequeryresultcachedaudio
-    telegram.inlinequeryresultcacheddocument
-    telegram.inlinequeryresultcachedgif
-    telegram.inlinequeryresultcachedmpeg4gif
-    telegram.inlinequeryresultcachedphoto
-    telegram.inlinequeryresultcachedsticker
-    telegram.inlinequeryresultcachedvideo
-    telegram.inlinequeryresultcachedvoice
-    telegram.inlinequeryresultcontact
-    telegram.inlinequeryresultdocument
-    telegram.inlinequeryresultgame
-    telegram.inlinequeryresultgif
-    telegram.inlinequeryresultlocation
-    telegram.inlinequeryresultmpeg4gif
-    telegram.inlinequeryresultphoto
-    telegram.inlinequeryresultvenue
-    telegram.inlinequeryresultvideo
-    telegram.inlinequeryresultvoice
-    telegram.inputmessagecontent
-    telegram.inputtextmessagecontent
-    telegram.inputlocationmessagecontent
-    telegram.inputvenuemessagecontent
-    telegram.inputcontactmessagecontent
-    telegram.inputinvoicemessagecontent
-    telegram.choseninlineresult
-
-Payments
---------
-
-.. toctree::
-
-    telegram.labeledprice
-    telegram.invoice
-    telegram.shippingaddress
-    telegram.orderinfo
-    telegram.shippingoption
-    telegram.successfulpayment
-    telegram.shippingquery
-    telegram.precheckoutquery
-
-Games
------
-
-.. toctree::
-
-    telegram.game
-    telegram.callbackgame
-    telegram.gamehighscore
-
-Passport
---------
-
-.. toctree::
-
-    telegram.passportelementerror
-    telegram.passportelementerrorfile
-    telegram.passportelementerrorfiles
-    telegram.passportelementerrorreverseside
-    telegram.passportelementerrorfrontside
-    telegram.passportelementerrordatafield
-    telegram.passportelementerrorselfie
-    telegram.passportelementerrortranslationfile
-    telegram.passportelementerrortranslationfiles
-    telegram.passportelementerrorunspecified
-    telegram.credentials
-    telegram.datacredentials
-    telegram.securedata
-    telegram.securevalue
-    telegram.filecredentials
-    telegram.iddocumentdata
-    telegram.personaldetails
-    telegram.residentialaddress
-    telegram.passportdata
-    telegram.passportfile
-    telegram.encryptedpassportelement
-    telegram.encryptedcredentials

docs/source/telegram.stickers-tree.rst

@@ -0,0 +1,9 @@
+Stickers
+--------
+
+.. toctree::
+    :titlesonly:
+
+    telegram.maskposition
+    telegram.sticker
+    telegram.stickerset

docs/source/telegram.telegramobject.rst

@@ -4,3 +4,4 @@ telegram.TelegramObject
 .. autoclass:: telegram.TelegramObject
     :members:
     :show-inheritance:
+    :special-members: __repr__, __getitem__, __eq__, __hash__, __setstate__, __getstate__, __deepcopy__, __setattr__, __delattr__

docs/source/telegram_auxil.rst

@@ -2,6 +2,7 @@ Auxiliary modules
 =================
 
 .. toctree::
+    :titlesonly:
 
     telegram.constants
     telegram.error

docs/substitutions/global.rst

@@ -0,0 +1,49 @@
+.. |uploadinput| replace:: To upload a file, you can either pass a :term:`file object` (e.g. ``open("filename", "rb")``), the file contents as bytes or the path of the file (as string or :class:`pathlib.Path` object). In the latter case, the file contents will either be read as bytes or the file path will be passed to Telegram, depending on the :paramref:`~telegram.Bot.local_mode` setting.
+
+.. |uploadinputnopath| replace:: To upload a file, you can either pass a :term:`file object` (e.g. ``open("filename", "rb")``) or the file contents as bytes. If the bot is running in :paramref:`~telegram.Bot.local_mode`, passing the path of the file (as string or :class:`pathlib.Path` object) is supported as well.
+
+.. |fileinputbase| replace:: Pass a ``file_id`` as String to send a file that exists on the Telegram servers (recommended), pass an HTTP URL as a String for Telegram to get a file from the Internet, or upload a new one.
+
+.. |fileinput| replace:: |fileinputbase| |uploadinput|
+
+.. |fileinputnopath| replace:: |fileinputbase| |uploadinputnopath|
+
+.. |thumbdocstringbase| replace:: Thumbnail of the file sent; can be ignored if thumbnail generation for the file is supported server-side. The thumbnail should be in JPEG format and less than 200 kB in size. A thumbnail's width and height should not exceed 320. Ignored if the file is not uploaded using multipart/form-data. Thumbnails can't be reused and can be only uploaded as a new file.
+
+.. |thumbdocstring| replace:: |thumbdocstringbase| |uploadinput|
+
+.. |thumbdocstringnopath| replace:: |thumbdocstringbase| |uploadinputnopath|
+
+.. |editreplymarkup| replace:: It is currently only possible to edit messages without :attr:`telegram.Message.reply_markup` or with inline keyboards.
+
+.. |toapikwargsbase| replace:: These arguments are also considered by :meth:`~telegram.TelegramObject.to_dict` and :meth:`~telegram.TelegramObject.to_json`, i.e. when passing objects to Telegram. Passing them to Telegram is however not guaranteed to work for all kinds of objects, e.g. this will fail for objects that can not directly be JSON serialized.
+
+.. |toapikwargsarg| replace:: Arbitrary keyword arguments. Can be used to store data for which there are no dedicated attributes. |toapikwargsbase|
+
+.. |toapikwargsattr| replace:: Optional. Arbitrary keyword arguments. Used to store data for which there are no dedicated attributes. |toapikwargsbase|
+
+.. |chat_id_channel| replace:: Unique identifier for the target chat or username of the target channel (in the format ``@channelusername``).
+
+.. |chat_id_group| replace:: Unique identifier for the target chat or username of the target supergroup (in the format ``@supergroupusername``).
+
+.. |message_thread_id| replace:: Unique identifier for the target message thread of the forum topic.
+
+.. |message_thread_id_arg| replace:: Unique identifier for the target message thread (topic) of the forum; for forum supergroups only.
+
+.. |parse_mode| replace:: Mode for parsing entities. See :class:`telegram.constants.ParseMode` and `formatting options <https://core.telegram.org/bots/api#formatting-options>`__ for more details.
+
+.. |allow_sending_without_reply| replace:: Pass :obj:`True`, if the message should be sent even if the specified replied-to message is not found.
+
+.. |caption_entities| replace:: List of special entities that appear in the caption, which can be specified instead of ``parse_mode``.
+
+.. |protect_content| replace:: Protects the contents of the sent message from forwarding and saving.
+
+.. |disable_notification| replace:: Sends the message silently. Users will receive a notification with no sound.
+
+.. |reply_to_msg_id| replace:: If the message is a reply, ID of the original message.
+
+.. |sequenceclassargs| replace:: Accepts any :class:`collections.abc.Sequence` as input instead of just a list. The input is converted to a tuple.
+
+.. |tupleclassattrs| replace:: This attribute is now an immutable tuple.
+
+.. |alwaystuple| replace:: This attribute is now always a tuple, that may be empty.

examples/README.md

@@ -1,61 +1,5 @@
 # Examples
 
-In this folder are small examples to show what a bot written with `python-telegram-bot` looks like. Some bots focus on one specific aspect of the Telegram Bot API while others focus on one of the mechanics of this library. Except for the [`rawapibot.py`](#pure-api) example, they all use the high-level framework this library provides with the [`telegram.ext`](https://python-telegram-bot.readthedocs.io/en/latest/telegram.ext.html) submodule.
+A description of the examples in this directory can be found in the [documentation](https://docs.python-telegram-bot.org/examples.html).
 
-All examples are licensed under the [CC0 License](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/LICENSE.txt) and are therefore fully dedicated to the public domain. You can use them as the base for your own bots without worrying about copyrights.
-
-Do note that we ignore one pythonic convention. Best practice would dictate, in many handler callbacks function signatures, to replace the argument `context` with an underscore, since `context` is an unused local variable in those callbacks. However, since these are examples and not having a name for that argument confuses beginners, we decided to have it present.
-
-### [`echobot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/echobot.py) 
-This is probably the base for most of the bots made with `python-telegram-bot`. It simply replies to each text message with a message that contains the same text.
-
-### [`timerbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/timerbot.py) 
-This bot uses the [`JobQueue`](https://python-telegram-bot.readthedocs.io/en/latest/telegram.ext.jobqueue.html) class to send timed messages. The user sets a timer by using `/set` command with a specific time, for example `/set 30`. The bot then sets up a job to send a message to that user after 30 seconds. The user can also cancel the timer by sending `/unset`. To learn more about the `JobQueue`, read [this wiki article](https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions-%E2%80%93-JobQueue).
-
-### [`conversationbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/conversationbot.py)
-A common task for a bot is to ask information from the user. In v5.0 of this library, we introduced the [`ConversationHandler`](https://python-telegram-bot.readthedocs.io/en/latest/telegram.ext.conversationhandler.html) for that exact purpose. This example uses it to retrieve user-information in a conversation-like style. To get a better understanding, take a look at the [state diagram](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/conversationbot.png).
-
-### [`conversationbot2.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/conversationbot2.py)
-A more complex example of a bot that uses the `ConversationHandler`. It is also more confusing. Good thing there is a [fancy state diagram](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/conversationbot2.png) for this one, too!
-
-### [`nestedconversationbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/nestedconversationbot.py)
-A even more complex example of a bot that uses the nested `ConversationHandler`s. While it's certainly not that complex that you couldn't built it without nested `ConversationHanldler`s, it gives a good impression on how to work with them. Of course, there is a [fancy state diagram](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/nestedconversationbot.png) for this example, too!
-
-### [`persistentconversationbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/persistentconversationbot.py)
-A basic example of a bot store conversation state and user_data over multiple restarts.
-
-### [`inlinekeyboard.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/inlinekeyboard.py)
-This example sheds some light on inline keyboards, callback queries and message editing. A wiki site explaining this examples lives [here](https://github.com/python-telegram-bot/python-telegram-bot/wiki/InlineKeyboard-Example).
-
-### [`inlinekeyboard2.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/inlinekeyboard2.py)
-A more complex example about inline keyboards, callback queries and message editing. This example showcases how an interactive menu could be build using inline keyboards.
-
-### [`deeplinking.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/deeplinking.py)
-A basic example on how to use deeplinking with inline keyboards.
-
-### [`inlinebot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/inlinebot.py)
-A basic example of an [inline bot](https://core.telegram.org/bots/inline). Don't forget to enable inline mode with [@BotFather](https://telegram.me/BotFather).
-
-### [`pollbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/pollbot.py)
-This example sheds some light on polls, poll answers and the corresponding handlers.
-
-### [`passportbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/passportbot.py)
-A basic example of a bot that can accept passports. Use in combination with [`passportbot.html`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/passportbot.html). Don't forget to enable and configure payments with [@BotFather](https://telegram.me/BotFather). Check out this [guide](https://github.com/python-telegram-bot/python-telegram-bot/wiki/Telegram-Passport) on Telegram passports in PTB.
-
-### [`paymentbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/paymentbot.py)
-A basic example of a bot that can accept payments. Don't forget to enable and configure payments with [@BotFather](https://telegram.me/BotFather).
-
-### [`errorhandlerbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/errorhandlerbot.py)
-A basic example on how to set up a custom error handler.
-
-### [`chatmemberbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/chatmemberbot.py)
-A basic example on how `(my_)chat_member` updates can be used.
-
-### [`contexttypesbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/contexttypesbot.py)
-This example showcases how `telegram.ext.ContextTypes` can be used to customize the `context` argument of handler and job callbacks.
-
-### [`arbitrarycallbackdatabot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/arbitrarycallbackdatabot.py)
-This example showcases how PTBs "arbitrary callback data" feature can be used.
-
-## Pure API
-The [`rawapibot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/rawapibot.py) example uses only the pure, "bare-metal" API wrapper.
+All examples are licensed under the [CC0 License](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/LICENSE.txt) and are therefore fully dedicated to the public domain. You can use them as the base for your own bots without worrying about copyrights.

examples/arbitrarycallbackdatabot.py

@@ -1,21 +1,38 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument
+# pylint: disable=unused-argument, wrong-import-position
 # This program is dedicated to the public domain under the CC0 license.
 
 """This example showcases how PTBs "arbitrary callback data" feature can be used.
 
 For detailed info on arbitrary callback data, see the wiki page at
 https://github.com/python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data
+
+Note:
+To use arbitrary callback data, you must install PTB via
+`pip install python-telegram-bot[callback-data]`
 """
 import logging
 from typing import List, Tuple, cast
 
+from telegram import __version__ as TG_VER
+
+try:
+    from telegram import __version_info__
+except ImportError:
+    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
+
+if __version_info__ < (20, 0, 0, "alpha", 1):
+    raise RuntimeError(
+        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
+        f"{TG_VER} version of this example, "
+        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
+    )
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
 from telegram.ext import (
     Application,
-    CallbackContext,
     CallbackQueryHandler,
     CommandHandler,
+    ContextTypes,
     InvalidCallbackData,
     PicklePersistence,
 )
@@ -27,13 +44,13 @@ logging.basicConfig(
 logger = logging.getLogger(__name__)
 
 
-async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Sends a message with 5 inline buttons attached."""
     number_list: List[int] = []
     await update.message.reply_text("Please choose:", reply_markup=build_keyboard(number_list))
 
 
-async def help_command(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def help_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Displays info on how to use the bot."""
     await update.message.reply_text(
         "Use /start to test this bot. Use /clear to clear the stored data so that you can see "
@@ -41,7 +58,7 @@ async def help_command(update: Update, context: CallbackContext.DEFAULT_TYPE) ->
     )
 
 
-async def clear(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def clear(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Clears the callback data cache"""
     context.bot.callback_data_cache.clear_callback_data()
     context.bot.callback_data_cache.clear_callback_queries()
@@ -55,7 +72,7 @@ def build_keyboard(current_list: List[int]) -> InlineKeyboardMarkup:
     )
 
 
-async def list_button(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def list_button(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Parses the CallbackQuery and updates the message text."""
     query = update.callback_query
     await query.answer()
@@ -75,7 +92,7 @@ async def list_button(update: Update, context: CallbackContext.DEFAULT_TYPE) ->
     context.drop_callback_data(query)
 
 
-async def handle_invalid_button(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def handle_invalid_button(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Informs the user that the button is no longer available."""
     await update.callback_query.answer()
     await update.effective_message.edit_text(

examples/chatmemberbot.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument
+# pylint: disable=unused-argument, wrong-import-position
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -14,9 +14,22 @@ bot.
 import logging
 from typing import Optional, Tuple
 
+from telegram import __version__ as TG_VER
+
+try:
+    from telegram import __version_info__
+except ImportError:
+    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
+
+if __version_info__ < (20, 0, 0, "alpha", 1):
+    raise RuntimeError(
+        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
+        f"{TG_VER} version of this example, "
+        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
+    )
 from telegram import Chat, ChatMember, ChatMemberUpdated, Update
 from telegram.constants import ParseMode
-from telegram.ext import Application, CallbackContext, ChatMemberHandler, CommandHandler
+from telegram.ext import Application, ChatMemberHandler, CommandHandler, ContextTypes
 
 # Enable logging
 
@@ -27,9 +40,7 @@ logging.basicConfig(
 logger = logging.getLogger(__name__)
 
 
-def extract_status_change(
-    chat_member_update: ChatMemberUpdated,
-) -> Optional[Tuple[bool, bool]]:
+def extract_status_change(chat_member_update: ChatMemberUpdated) -> Optional[Tuple[bool, bool]]:
     """Takes a ChatMemberUpdated instance and extracts whether the 'old_chat_member' was a member
     of the chat and whether the 'new_chat_member' is a member of the chat. Returns None, if
     the status didn't change.
@@ -55,7 +66,7 @@ def extract_status_change(
     return was_member, is_member
 
 
-async def track_chats(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def track_chats(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Tracks the chats the bot is in."""
     result = extract_status_change(update.my_chat_member)
     if result is None:
@@ -90,7 +101,7 @@ async def track_chats(update: Update, context: CallbackContext.DEFAULT_TYPE) ->
             context.bot_data.setdefault("channel_ids", set()).discard(chat.id)
 
 
-async def show_chats(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def show_chats(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Shows which chats the bot is in"""
     user_ids = ", ".join(str(uid) for uid in context.bot_data.setdefault("user_ids", set()))
     group_ids = ", ".join(str(gid) for gid in context.bot_data.setdefault("group_ids", set()))
@@ -103,7 +114,7 @@ async def show_chats(update: Update, context: CallbackContext.DEFAULT_TYPE) -> N
     await update.effective_message.reply_text(text)
 
 
-async def greet_chat_members(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def greet_chat_members(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Greets new users in chats and announces when someone leaves"""
     result = extract_status_change(update.chat_member)
     if result is None:

examples/contexttypesbot.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument
+# pylint: disable=unused-argument, wrong-import-position
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -14,6 +14,19 @@ import logging
 from collections import defaultdict
 from typing import DefaultDict, Optional, Set
 
+from telegram import __version__ as TG_VER
+
+try:
+    from telegram import __version_info__
+except ImportError:
+    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
+
+if __version_info__ < (20, 0, 0, "alpha", 1):
+    raise RuntimeError(
+        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
+        f"{TG_VER} version of this example, "
+        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
+    )
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
 from telegram.constants import ParseMode
 from telegram.ext import (
@@ -44,8 +57,8 @@ class ChatData:
 class CustomContext(CallbackContext[ExtBot, dict, ChatData, dict]):
     """Custom class for context."""
 
-    def __init__(self, application: Application):
-        super().__init__(application=application)
+    def __init__(self, application: Application, chat_id: int = None, user_id: int = None):
+        super().__init__(application=application, chat_id=chat_id, user_id=user_id)
         self._message_id: Optional[int] = None
 
     @property

examples/conversationbot.mmd

@@ -0,0 +1,21 @@
+flowchart TB
+    %% Documentation: https://mermaid-js.github.io/mermaid/#/flowchart
+    A(("/start")):::entryPoint -->|Hi! My name is Professor Bot...| B((GENDER)):::state
+    B --> |"- Boy <br /> - Girl <br /> - Other"|C("(choice)"):::userInput 
+    C --> |I see! Please send me a photo...| D((PHOTO)):::state
+    D --> E("/skip"):::userInput
+    D --> F("(photo)"):::userInput
+    E --> |I bet you look great!| G[\ /]:::userInput
+    F --> |Gorgeous!| G[\ /]
+    G --> |"Now, send me your location .."| H((LOCATION)):::state
+    H --> I("/skip"):::userInput
+    H --> J("(location)"):::userInput
+    I --> |You seem a bit paranoid!| K[\" "/]:::userInput
+    J --> |Maybe I can visit...| K
+    K --> |"Tell me about yourself..."| L(("BIO")):::state
+    L --> M("(text)"):::userInput
+    M --> |"Thanks and bye!"| End(("END")):::termination
+    classDef userInput  fill:#2a5279, color:#ffffff, stroke:#ffffff
+    classDef state fill:#222222, color:#ffffff, stroke:#ffffff
+    classDef entryPoint fill:#009c11, stroke:#42FF57, color:#ffffff
+    classDef termination fill:#bb0007, stroke:#E60109, color:#ffffff

examples/conversationbot.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument
+# pylint: disable=unused-argument, wrong-import-position
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -16,11 +16,24 @@ bot.
 
 import logging
 
+from telegram import __version__ as TG_VER
+
+try:
+    from telegram import __version_info__
+except ImportError:
+    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
+
+if __version_info__ < (20, 0, 0, "alpha", 5):
+    raise RuntimeError(
+        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
+        f"{TG_VER} version of this example, "
+        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
+    )
 from telegram import ReplyKeyboardMarkup, ReplyKeyboardRemove, Update
 from telegram.ext import (
     Application,
-    CallbackContext,
     CommandHandler,
+    ContextTypes,
     ConversationHandler,
     MessageHandler,
     filters,
@@ -35,7 +48,7 @@ logger = logging.getLogger(__name__)
 GENDER, PHOTO, LOCATION, BIO = range(4)
 
 
-async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Starts the conversation and asks the user about their gender."""
     reply_keyboard = [["Boy", "Girl", "Other"]]
 
@@ -51,7 +64,7 @@ async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
     return GENDER
 
 
-async def gender(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def gender(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Stores the selected gender and asks for a photo."""
     user = update.message.from_user
     logger.info("Gender of %s: %s", user.first_name, update.message.text)
@@ -64,11 +77,11 @@ async def gender(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
     return PHOTO
 
 
-async def photo(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def photo(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Stores the photo and asks for a location."""
     user = update.message.from_user
     photo_file = await update.message.photo[-1].get_file()
-    await photo_file.download("user_photo.jpg")
+    await photo_file.download_to_drive("user_photo.jpg")
     logger.info("Photo of %s: %s", user.first_name, "user_photo.jpg")
     await update.message.reply_text(
         "Gorgeous! Now, send me your location please, or send /skip if you don't want to."
@@ -77,7 +90,7 @@ async def photo(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
     return LOCATION
 
 
-async def skip_photo(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def skip_photo(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Skips the photo and asks for a location."""
     user = update.message.from_user
     logger.info("User %s did not send a photo.", user.first_name)
@@ -88,7 +101,7 @@ async def skip_photo(update: Update, context: CallbackContext.DEFAULT_TYPE) -> i
     return LOCATION
 
 
-async def location(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def location(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Stores the location and asks for some info about the user."""
     user = update.message.from_user
     user_location = update.message.location
@@ -102,7 +115,7 @@ async def location(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int
     return BIO
 
 
-async def skip_location(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def skip_location(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Skips the location and asks for info about the user."""
     user = update.message.from_user
     logger.info("User %s did not send a location.", user.first_name)
@@ -113,7 +126,7 @@ async def skip_location(update: Update, context: CallbackContext.DEFAULT_TYPE) -
     return BIO
 
 
-async def bio(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def bio(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Stores the info about the user and ends the conversation."""
     user = update.message.from_user
     logger.info("Bio of %s: %s", user.first_name, update.message.text)
@@ -122,7 +135,7 @@ async def bio(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
     return ConversationHandler.END
 
 
-async def cancel(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def cancel(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Cancels and ends the conversation."""
     user = update.message.from_user
     logger.info("User %s canceled the conversation.", user.first_name)

examples/conversationbot2.mmd

@@ -0,0 +1,17 @@
+flowchart TB
+    %% Documentation: https://mermaid-js.github.io/mermaid/#/flowchart
+    A(("/start")):::entryPoint -->|Hi! My name is Doctor Botter...| B((CHOOSING)):::state
+    B --> C("Something else..."):::userInput 
+    C --> |What category?| D((TYPING_CHOICE)):::state
+    D --> E("(text)"):::userInput
+    E --> |"[save choice] <br /> I'd love to hear about that!"| F((TYPING_REPLY)):::state
+    F --> G("(text)"):::userInput
+    G --> |"[save choice: text] <br /> Neat! <br /> (List of facts) <br /> More?"| B
+    B --> H("- Age <br /> - Favourite colour <br /> - Number of siblings"):::userInput
+    H --> |"[save choice] <br /> I'd love to hear about that!"| F
+    B --> I("Done"):::userInput
+    I --> |"I learned these facts about you: <br /> ..."| End(("END")):::termination
+    classDef userInput  fill:#2a5279, color:#ffffff, stroke:#ffffff
+    classDef state fill:#222222, color:#ffffff, stroke:#ffffff
+    classDef entryPoint fill:#009c11, stroke:#42FF57, color:#ffffff
+    classDef termination fill:#bb0007, stroke:#E60109, color:#ffffff

examples/conversationbot2.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument
+# pylint: disable=unused-argument, wrong-import-position
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -17,11 +17,24 @@ bot.
 import logging
 from typing import Dict
 
+from telegram import __version__ as TG_VER
+
+try:
+    from telegram import __version_info__
+except ImportError:
+    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
+
+if __version_info__ < (20, 0, 0, "alpha", 1):
+    raise RuntimeError(
+        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
+        f"{TG_VER} version of this example, "
+        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
+    )
 from telegram import ReplyKeyboardMarkup, ReplyKeyboardRemove, Update
 from telegram.ext import (
     Application,
-    CallbackContext,
     CommandHandler,
+    ContextTypes,
     ConversationHandler,
     MessageHandler,
     filters,
@@ -49,7 +62,7 @@ def facts_to_str(user_data: Dict[str, str]) -> str:
     return "\n".join(facts).join(["\n", "\n"])
 
 
-async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Start the conversation and ask user for input."""
     await update.message.reply_text(
         "Hi! My name is Doctor Botter. I will hold a more complex conversation with you. "
@@ -60,7 +73,7 @@ async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
     return CHOOSING
 
 
-async def regular_choice(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def regular_choice(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Ask the user for info about the selected predefined choice."""
     text = update.message.text
     context.user_data["choice"] = text
@@ -69,7 +82,7 @@ async def regular_choice(update: Update, context: CallbackContext.DEFAULT_TYPE)
     return TYPING_REPLY
 
 
-async def custom_choice(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def custom_choice(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Ask the user for a description of a custom category."""
     await update.message.reply_text(
         'Alright, please send me the category first, for example "Most impressive skill"'
@@ -78,7 +91,7 @@ async def custom_choice(update: Update, context: CallbackContext.DEFAULT_TYPE) -
     return TYPING_CHOICE
 
 
-async def received_information(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def received_information(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Store info provided by user and ask for the next category."""
     user_data = context.user_data
     text = update.message.text
@@ -96,7 +109,7 @@ async def received_information(update: Update, context: CallbackContext.DEFAULT_
     return CHOOSING
 
 
-async def done(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def done(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Display the gathered info and end the conversation."""
     user_data = context.user_data
     if "choice" in user_data:

examples/customwebhookbot.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python
+# This program is dedicated to the public domain under the CC0 license.
+# pylint: disable=import-error,wrong-import-position
+"""
+Simple example of a bot that uses a custom webhook setup and handles custom updates.
+For the custom webhook setup, the libraries `starlette` and `uvicorn` are used. Please install
+them as `pip install starlette~=0.20.0 uvicorn~=0.17.0`.
+Note that any other `asyncio` based web server framework can be used for a custom webhook setup
+just as well.
+
+Usage:
+Set bot token, url, admin chat_id and port at the start of the `main` function.
+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
+from dataclasses import dataclass
+from http import HTTPStatus
+
+import uvicorn
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse, Response
+from starlette.routing import Route
+
+from telegram import __version__ as TG_VER
+
+try:
+    from telegram import __version_info__
+except ImportError:
+    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
+
+if __version_info__ < (20, 0, 0, "alpha", 1):
+    raise RuntimeError(
+        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
+        f"{TG_VER} version of this example, "
+        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
+    )
+
+from telegram import Update
+from telegram.constants import ParseMode
+from telegram.ext import (
+    Application,
+    CallbackContext,
+    CommandHandler,
+    ContextTypes,
+    ExtBot,
+    TypeHandler,
+)
+
+# Enable logging
+logging.basicConfig(
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", level=logging.INFO
+)
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class WebhookUpdate:
+    """Simple dataclass to wrap a custom update type"""
+
+    user_id: int
+    payload: str
+
+
+class CustomContext(CallbackContext[ExtBot, dict, dict, dict]):
+    """
+    Custom CallbackContext class that makes `user_data` available for updates of type
+    `WebhookUpdate`.
+    """
+
+    @classmethod
+    def from_update(
+        cls,
+        update: object,
+        application: "Application",
+    ) -> "CustomContext":
+        if isinstance(update, WebhookUpdate):
+            return cls(application=application, user_id=update.user_id)
+        return super().from_update(update, application)
+
+
+async def start(update: Update, context: CustomContext) -> None:
+    """Display a message with instructions on how to use this bot."""
+    url = context.bot_data["url"]
+    payload_url = html.escape(f"{url}/submitpayload?user_id=<your user id>&payload=<payload>")
+    text = (
+        f"To check if the bot is still running, call <code>{url}/healthcheck</code>.\n\n"
+        f"To post a custom update, call <code>{payload_url}</code>."
+    )
+    await update.message.reply_html(text=text)
+
+
+async def webhook_update(update: WebhookUpdate, context: CustomContext) -> None:
+    """Callback that handles the custom updates."""
+    chat_member = await context.bot.get_chat_member(chat_id=update.user_id, user_id=update.user_id)
+    payloads = context.user_data.setdefault("payloads", [])
+    payloads.append(update.payload)
+    combined_payloads = "</code>\n• <code>".join(payloads)
+    text = (
+        f"The user {chat_member.user.mention_html()} has sent a new payload. "
+        f"So far they have sent the following payloads: \n\n• <code>{combined_payloads}</code>"
+    )
+    await context.bot.send_message(
+        chat_id=context.bot_data["admin_chat_id"], text=text, parse_mode=ParseMode.HTML
+    )
+
+
+async def main() -> None:
+    """Set up the application and a custom webserver."""
+    url = "https://domain.tld"
+    admin_chat_id = 123456
+    port = 8000
+
+    context_types = ContextTypes(context=CustomContext)
+    # Here we set updater to None because we want our custom webhook server to handle the updates
+    # and hence we don't need an Updater instance
+    application = (
+        Application.builder().token("TOKEN").updater(None).context_types(context_types).build()
+    )
+    # save the values in `bot_data` such that we may easily access them in the callbacks
+    application.bot_data["url"] = url
+    application.bot_data["admin_chat_id"] = admin_chat_id
+
+    # register handlers
+    application.add_handler(CommandHandler("start", start))
+    application.add_handler(TypeHandler(type=WebhookUpdate, callback=webhook_update))
+
+    # Pass webhook settings to telegram
+    await application.bot.set_webhook(url=f"{url}/telegram")
+
+    # Set up webserver
+    async def telegram(request: Request) -> Response:
+        """Handle incoming Telegram updates by putting them into the `update_queue`"""
+        await application.update_queue.put(
+            Update.de_json(data=await request.json(), bot=application.bot)
+        )
+        return Response()
+
+    async def custom_updates(request: Request) -> PlainTextResponse:
+        """
+        Handle incoming webhook updates by also putting them into the `update_queue` if
+        the required parameters were passed correctly.
+        """
+        try:
+            user_id = int(request.query_params["user_id"])
+            payload = request.query_params["payload"]
+        except KeyError:
+            return PlainTextResponse(
+                status_code=HTTPStatus.BAD_REQUEST,
+                content="Please pass both `user_id` and `payload` as query parameters.",
+            )
+        except ValueError:
+            return PlainTextResponse(
+                status_code=HTTPStatus.BAD_REQUEST,
+                content="The `user_id` must be a string!",
+            )
+
+        await application.update_queue.put(WebhookUpdate(user_id=user_id, payload=payload))
+        return PlainTextResponse("Thank you for the submission! It's being forwarded.")
+
+    async def health(_: Request) -> PlainTextResponse:
+        """For the health endpoint, reply with a simple plain text message."""
+        return PlainTextResponse(content="The bot is still running fine :)")
+
+    starlette_app = Starlette(
+        routes=[
+            Route("/telegram", telegram, methods=["POST"]),
+            Route("/healthcheck", health, methods=["GET"]),
+            Route("/submitpayload", custom_updates, methods=["POST", "GET"]),
+        ]
+    )
+    webserver = uvicorn.Server(
+        config=uvicorn.Config(
+            app=starlette_app,
+            port=port,
+            use_colors=False,
+            host="127.0.0.1",
+        )
+    )
+
+    # Run application and webserver together
+    async with application:
+        await application.start()
+        await webserver.serve()
+        await application.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/deeplinking.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument
+# pylint: disable=unused-argument, wrong-import-position
 # This program is dedicated to the public domain under the CC0 license.
 
 """Bot that explains Telegram's "Deep Linking Parameters" functionality.
@@ -20,15 +20,22 @@ bot.
 
 import logging
 
+from telegram import __version__ as TG_VER
+
+try:
+    from telegram import __version_info__
+except ImportError:
+    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
+
+if __version_info__ < (20, 0, 0, "alpha", 1):
+    raise RuntimeError(
+        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
+        f"{TG_VER} version of this example, "
+        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
+    )
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update, helpers
 from telegram.constants import ParseMode
-from telegram.ext import (
-    Application,
-    CallbackContext,
-    CallbackQueryHandler,
-    CommandHandler,
-    filters,
-)
+from telegram.ext import Application, CallbackQueryHandler, CommandHandler, ContextTypes, filters
 
 # Enable logging
 logging.basicConfig(
@@ -47,7 +54,7 @@ SO_COOL = "so-cool"
 KEYBOARD_CALLBACKDATA = "keyboard-callback-data"
 
 
-async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Send a deep-linked URL when the command /start is issued."""
     bot = context.bot
     url = helpers.create_deep_linked_url(bot.username, CHECK_THIS_OUT, group=True)
@@ -55,7 +62,7 @@ async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
     await update.message.reply_text(text)
 
 
-async def deep_linked_level_1(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def deep_linked_level_1(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Reached through the CHECK_THIS_OUT payload"""
     bot = context.bot
     url = helpers.create_deep_linked_url(bot.username, SO_COOL)
@@ -69,7 +76,7 @@ async def deep_linked_level_1(update: Update, context: CallbackContext.DEFAULT_T
     await update.message.reply_text(text, reply_markup=keyboard)
 
 
-async def deep_linked_level_2(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def deep_linked_level_2(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Reached through the SO_COOL payload"""
     bot = context.bot
     url = helpers.create_deep_linked_url(bot.username, USING_ENTITIES)
@@ -77,7 +84,7 @@ async def deep_linked_level_2(update: Update, context: CallbackContext.DEFAULT_T
     await update.message.reply_text(text, parse_mode=ParseMode.HTML, disable_web_page_preview=True)
 
 
-async def deep_linked_level_3(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def deep_linked_level_3(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Reached through the USING_ENTITIES payload"""
     await update.message.reply_text(
         "It is also possible to make deep-linking using InlineKeyboardButtons.",
@@ -87,16 +94,14 @@ async def deep_linked_level_3(update: Update, context: CallbackContext.DEFAULT_T
     )
 
 
-async def deep_link_level_3_callback(
-    update: Update, context: CallbackContext.DEFAULT_TYPE
-) -> None:
+async def deep_link_level_3_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Answers CallbackQuery with deeplinking url."""
     bot = context.bot
     url = helpers.create_deep_linked_url(bot.username, USING_KEYBOARD)
     await update.callback_query.answer(url=url)
 
 
-async def deep_linked_level_4(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def deep_linked_level_4(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Reached through the USING_KEYBOARD payload"""
     payload = context.args
     await update.message.reply_text(
@@ -110,7 +115,7 @@ def main() -> None:
     application = Application.builder().token("TOKEN").build()
 
     # More info on what deep linking actually is (read this first if it's unclear to you):
-    # https://core.telegram.org/bots#deep-linking
+    # https://core.telegram.org/bots/features#deep-linking
 
     # Register a deep-linking handler
     application.add_handler(

examples/echobot.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument
+# pylint: disable=unused-argument, wrong-import-position
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -17,8 +17,21 @@ bot.
 
 import logging
 
+from telegram import __version__ as TG_VER
+
+try:
+    from telegram import __version_info__
+except ImportError:
+    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
+
+if __version_info__ < (20, 0, 0, "alpha", 1):
+    raise RuntimeError(
+        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
+        f"{TG_VER} version of this example, "
+        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
+    )
 from telegram import ForceReply, Update
-from telegram.ext import Application, CallbackContext, CommandHandler, MessageHandler, filters
+from telegram.ext import Application, CommandHandler, ContextTypes, MessageHandler, filters
 
 # Enable logging
 logging.basicConfig(
@@ -29,7 +42,7 @@ logger = logging.getLogger(__name__)
 
 # Define a few command handlers. These usually take the two arguments update and
 # context.
-async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Send a message when the command /start is issued."""
     user = update.effective_user
     await update.message.reply_html(
@@ -38,12 +51,12 @@ async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
     )
 
 
-async def help_command(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def help_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Send a message when the command /help is issued."""
     await update.message.reply_text("Help!")
 
 
-async def echo(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Echo the user message."""
     await update.message.reply_text(update.message.text)
 

examples/errorhandlerbot.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument
+# pylint: disable=unused-argument, wrong-import-position
 # 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."""
@@ -8,9 +8,22 @@ import json
 import logging
 import traceback
 
+from telegram import __version__ as TG_VER
+
+try:
+    from telegram import __version_info__
+except ImportError:
+    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
+
+if __version_info__ < (20, 0, 0, "alpha", 1):
+    raise RuntimeError(
+        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
+        f"{TG_VER} version of this example, "
+        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
+    )
 from telegram import Update
 from telegram.constants import ParseMode
-from telegram.ext import Application, CallbackContext, CommandHandler
+from telegram.ext import Application, CommandHandler, ContextTypes
 
 # Enable logging
 logging.basicConfig(
@@ -23,7 +36,7 @@ logger = logging.getLogger(__name__)
 DEVELOPER_CHAT_ID = 123456789
 
 
-async def error_handler(update: object, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def error_handler(update: object, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Log the error and send a telegram message to notify the developer."""
     # Log the error before we do anything else, so we can see it even if something breaks.
     logger.error(msg="Exception while handling an update:", exc_info=context.error)
@@ -51,12 +64,12 @@ async def error_handler(update: object, context: CallbackContext.DEFAULT_TYPE) -
     )
 
 
-async def bad_command(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def bad_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Raise an error to trigger the error handler."""
     await context.bot.wrong_method_name()  # type: ignore[attr-defined]
 
 
-async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Displays info on how to trigger an error."""
     await update.effective_message.reply_html(
         "Use /bad_command to cause an error.\n"

examples/inlinebot.py

@@ -1,8 +1,10 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument
+# pylint: disable=unused-argument, wrong-import-position
 # This program is dedicated to the public domain under the CC0 license.
 
 """
+Don't forget to enable inline mode with @BotFather
+
 First, a few handler functions are defined. Then, those functions are passed to
 the Application and registered at their respective places.
 Then, the bot is started and runs until we press Ctrl-C on the command line.
@@ -16,9 +18,22 @@ import logging
 from html import escape
 from uuid import uuid4
 
+from telegram import __version__ as TG_VER
+
+try:
+    from telegram import __version_info__
+except ImportError:
+    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
+
+if __version_info__ < (20, 0, 0, "alpha", 1):
+    raise RuntimeError(
+        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
+        f"{TG_VER} version of this example, "
+        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
+    )
 from telegram import InlineQueryResultArticle, InputTextMessageContent, Update
 from telegram.constants import ParseMode
-from telegram.ext import Application, CallbackContext, CommandHandler, InlineQueryHandler
+from telegram.ext import Application, CommandHandler, ContextTypes, InlineQueryHandler
 
 # Enable logging
 logging.basicConfig(
@@ -29,17 +44,17 @@ logger = logging.getLogger(__name__)
 
 # Define a few command handlers. These usually take the two arguments update and
 # context.
-async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Send a message when the command /start is issued."""
     await update.message.reply_text("Hi!")
 
 
-async def help_command(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def help_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Send a message when the command /help is issued."""
     await update.message.reply_text("Help!")
 
 
-async def inline_query(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def inline_query(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Handle the inline query. This is run when you type: @botusername <query>"""
     query = update.inline_query.query
 

examples/inlinekeyboard.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument
+# pylint: disable=unused-argument, wrong-import-position
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -8,8 +8,21 @@ Basic example for a bot that uses inline keyboards. For an in-depth explanation,
 """
 import logging
 
+from telegram import __version__ as TG_VER
+
+try:
+    from telegram import __version_info__
+except ImportError:
+    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
+
+if __version_info__ < (20, 0, 0, "alpha", 1):
+    raise RuntimeError(
+        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
+        f"{TG_VER} version of this example, "
+        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
+    )
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
-from telegram.ext import Application, CallbackContext, CallbackQueryHandler, CommandHandler
+from telegram.ext import Application, CallbackQueryHandler, CommandHandler, ContextTypes
 
 # Enable logging
 logging.basicConfig(
@@ -18,7 +31,7 @@ logging.basicConfig(
 logger = logging.getLogger(__name__)
 
 
-async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Sends a message with three inline buttons attached."""
     keyboard = [
         [
@@ -33,7 +46,7 @@ async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
     await update.message.reply_text("Please choose:", reply_markup=reply_markup)
 
 
-async def button(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def button(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Parses the CallbackQuery and updates the message text."""
     query = update.callback_query
 
@@ -44,7 +57,7 @@ async def button(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
     await query.edit_message_text(text=f"Selected option: {query.data}")
 
 
-async def help_command(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def help_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Displays info on how to use the bot."""
     await update.message.reply_text("Use /start to test this bot.")
 

examples/inlinekeyboard2.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument
+# pylint: disable=unused-argument, wrong-import-position
 # This program is dedicated to the public domain under the CC0 license.
 
 """Simple inline keyboard bot with multiple CallbackQueryHandlers.
@@ -16,12 +16,25 @@ Press Ctrl-C on the command line to stop the bot.
 """
 import logging
 
+from telegram import __version__ as TG_VER
+
+try:
+    from telegram import __version_info__
+except ImportError:
+    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
+
+if __version_info__ < (20, 0, 0, "alpha", 1):
+    raise RuntimeError(
+        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
+        f"{TG_VER} version of this example, "
+        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
+    )
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
 from telegram.ext import (
     Application,
-    CallbackContext,
     CallbackQueryHandler,
     CommandHandler,
+    ContextTypes,
     ConversationHandler,
 )
 
@@ -37,7 +50,7 @@ START_ROUTES, END_ROUTES = range(2)
 ONE, TWO, THREE, FOUR = range(4)
 
 
-async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Send message on `/start`."""
     # Get user that sent /start and log his name
     user = update.message.from_user
@@ -59,7 +72,7 @@ async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
     return START_ROUTES
 
 
-async def start_over(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def start_over(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Prompt same text & keyboard as `start` does but not as new message"""
     # Get CallbackQuery from Update
     query = update.callback_query
@@ -80,7 +93,7 @@ async def start_over(update: Update, context: CallbackContext.DEFAULT_TYPE) -> i
     return START_ROUTES
 
 
-async def one(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def one(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Show new choice of buttons"""
     query = update.callback_query
     await query.answer()
@@ -97,7 +110,7 @@ async def one(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
     return START_ROUTES
 
 
-async def two(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def two(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Show new choice of buttons"""
     query = update.callback_query
     await query.answer()
@@ -114,7 +127,7 @@ async def two(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
     return START_ROUTES
 
 
-async def three(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def three(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Show new choice of buttons. This is the end point of the conversation."""
     query = update.callback_query
     await query.answer()
@@ -132,7 +145,7 @@ async def three(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
     return END_ROUTES
 
 
-async def four(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def four(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Show new choice of buttons"""
     query = update.callback_query
     await query.answer()
@@ -149,7 +162,7 @@ async def four(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
     return START_ROUTES
 
 
-async def end(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def end(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Returns `ConversationHandler.END`, which tells the
     ConversationHandler that the conversation is over.
     """

examples/nestedconversationbot.mmd

@@ -0,0 +1,43 @@
+flowchart TB
+    %% Documentation: https://mermaid-js.github.io/mermaid/#/flowchart
+    A(("/start")):::entryPoint -->|Hi! I'm FamilyBot...| B((SELECTING_ACTION)):::state
+    B --> C("Show Data"):::userInput 
+    C --> |"(List of gathered data)"| D((SHOWING)):::state
+    D --> E("Back"):::userInput
+    E --> B
+    B --> F("Add Yourself"):::userInput
+    F --> G(("DESCRIBING_SELF")):::state
+    G --> H("Add info"):::userInput
+    H --> I((SELECT_FEATURE)):::state
+    I --> |"Please select a feature to update. <br /> - Name <br /> - Age <br /> - Done"|J("(choice)"):::userInput
+    J --> |"Okay, tell me."| K((TYPING)):::state
+    K --> L("(text)"):::userInput
+    L --> |"[saving]"|I
+    I --> M("Done"):::userInput
+    M --> B
+    B --> N("Add family member"):::userInput
+    R --> I
+    W --> |"See you around!"|End(("END")):::termination
+    Y(("ANY STATE")):::state --> Z("/stop"):::userInput
+    Z -->|"Okay, bye."| End
+    B --> W("Done"):::userInput
+    subgraph nestedConversation[Nested Conversation: Add Family Member]
+        direction BT
+        N --> O(("SELECT_LEVEL")):::state
+        O --> |"Add... <br /> - Add Parent <br /> - Add Child <br />"|P("(choice)"):::userInput
+        P -->  Q(("SELECT_GENDER")):::state
+        Q --> |"- Mother <br /> - Father <br /> / <br /> - Sister <br /> - Brother"| R("(choice)"):::userInput
+        Q --> V("Show Data"):::userInput
+        Q --> T(("SELECTING_ACTION")):::state
+        Q --> U("Back"):::userInput
+        U --> T
+        O --> U
+        O --> V
+        V --> S(("SHOWING")):::state
+        V --> T
+    end
+    classDef userInput  fill:#2a5279, color:#ffffff, stroke:#ffffff
+    classDef state fill:#222222, color:#ffffff, stroke:#ffffff
+    classDef entryPoint fill:#009c11, stroke:#42FF57, color:#ffffff
+    classDef termination fill:#bb0007, stroke:#E60109, color:#ffffff
+    style nestedConversation fill:#999999, stroke-width:2px, stroke:#333333

examples/nestedconversationbot.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument
+# pylint: disable=unused-argument, wrong-import-position
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -17,12 +17,25 @@ bot.
 import logging
 from typing import Any, Dict, Tuple
 
+from telegram import __version__ as TG_VER
+
+try:
+    from telegram import __version_info__
+except ImportError:
+    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
+
+if __version_info__ < (20, 0, 0, "alpha", 1):
+    raise RuntimeError(
+        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
+        f"{TG_VER} version of this example, "
+        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
+    )
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
 from telegram.ext import (
     Application,
-    CallbackContext,
     CallbackQueryHandler,
     CommandHandler,
+    ContextTypes,
     ConversationHandler,
     MessageHandler,
     filters,
@@ -70,7 +83,7 @@ def _name_switcher(level: str) -> Tuple[str, str]:
 
 
 # Top level conversation callbacks
-async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> str:
+async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> str:
     """Select an action: Adding parent/child or show data."""
     text = (
         "You may choose to add a family member, yourself, show the gathered data, or end the "
@@ -103,7 +116,7 @@ async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> str:
     return SELECTING_ACTION
 
 
-async def adding_self(update: Update, context: CallbackContext.DEFAULT_TYPE) -> str:
+async def adding_self(update: Update, context: ContextTypes.DEFAULT_TYPE) -> str:
     """Add information about yourself."""
     context.user_data[CURRENT_LEVEL] = SELF
     text = "Okay, please tell me about yourself."
@@ -116,7 +129,7 @@ async def adding_self(update: Update, context: CallbackContext.DEFAULT_TYPE) ->
     return DESCRIBING_SELF
 
 
-async def show_data(update: Update, context: CallbackContext.DEFAULT_TYPE) -> str:
+async def show_data(update: Update, context: ContextTypes.DEFAULT_TYPE) -> str:
     """Pretty print gathered data."""
 
     def pretty_print(data: Dict[str, Any], level: str) -> str:
@@ -153,14 +166,14 @@ async def show_data(update: Update, context: CallbackContext.DEFAULT_TYPE) -> st
     return SHOWING
 
 
-async def stop(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def stop(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """End Conversation by command."""
     await update.message.reply_text("Okay, bye.")
 
     return END
 
 
-async def end(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def end(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """End conversation from InlineKeyboardButton."""
     await update.callback_query.answer()
 
@@ -171,7 +184,7 @@ async def end(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
 
 
 # Second level conversation callbacks
-async def select_level(update: Update, context: CallbackContext.DEFAULT_TYPE) -> str:
+async def select_level(update: Update, context: ContextTypes.DEFAULT_TYPE) -> str:
     """Choose to add a parent or a child."""
     text = "You may add a parent or a child. Also you can show the gathered data or go back."
     buttons = [
@@ -192,7 +205,7 @@ async def select_level(update: Update, context: CallbackContext.DEFAULT_TYPE) ->
     return SELECTING_LEVEL
 
 
-async def select_gender(update: Update, context: CallbackContext.DEFAULT_TYPE) -> str:
+async def select_gender(update: Update, context: ContextTypes.DEFAULT_TYPE) -> str:
     """Choose to add mother or father."""
     level = update.callback_query.data
     context.user_data[CURRENT_LEVEL] = level
@@ -219,7 +232,7 @@ async def select_gender(update: Update, context: CallbackContext.DEFAULT_TYPE) -
     return SELECTING_GENDER
 
 
-async def end_second_level(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def end_second_level(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Return to top level conversation."""
     context.user_data[START_OVER] = True
     await start(update, context)
@@ -228,7 +241,7 @@ async def end_second_level(update: Update, context: CallbackContext.DEFAULT_TYPE
 
 
 # Third level callbacks
-async def select_feature(update: Update, context: CallbackContext.DEFAULT_TYPE) -> str:
+async def select_feature(update: Update, context: ContextTypes.DEFAULT_TYPE) -> str:
     """Select a feature to update for the person."""
     buttons = [
         [
@@ -255,7 +268,7 @@ async def select_feature(update: Update, context: CallbackContext.DEFAULT_TYPE)
     return SELECTING_FEATURE
 
 
-async def ask_for_input(update: Update, context: CallbackContext.DEFAULT_TYPE) -> str:
+async def ask_for_input(update: Update, context: ContextTypes.DEFAULT_TYPE) -> str:
     """Prompt user to input data for selected feature."""
     context.user_data[CURRENT_FEATURE] = update.callback_query.data
     text = "Okay, tell me."
@@ -266,7 +279,7 @@ async def ask_for_input(update: Update, context: CallbackContext.DEFAULT_TYPE) -
     return TYPING
 
 
-async def save_input(update: Update, context: CallbackContext.DEFAULT_TYPE) -> str:
+async def save_input(update: Update, context: ContextTypes.DEFAULT_TYPE) -> str:
     """Save input for feature and return to feature selection."""
     user_data = context.user_data
     user_data[FEATURES][user_data[CURRENT_FEATURE]] = update.message.text
@@ -276,7 +289,7 @@ async def save_input(update: Update, context: CallbackContext.DEFAULT_TYPE) -> s
     return await select_feature(update, context)
 
 
-async def end_describing(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def end_describing(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """End gathering of features and return to parent conversation."""
     user_data = context.user_data
     level = user_data[CURRENT_LEVEL]
@@ -294,7 +307,7 @@ async def end_describing(update: Update, context: CallbackContext.DEFAULT_TYPE)
     return END
 
 
-async def stop_nested(update: Update, context: CallbackContext.DEFAULT_TYPE) -> str:
+async def stop_nested(update: Update, context: ContextTypes.DEFAULT_TYPE) -> str:
     """Completely end conversation from within nested conversation."""
     await update.message.reply_text("Okay, bye.")
 

examples/passportbot.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument
+# pylint: disable=unused-argument, wrong-import-position
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -10,12 +10,28 @@ See https://telegram.org/blog/passport for info about what telegram passport is.
 See https://github.com/python-telegram-bot/python-telegram-bot/wiki/Telegram-Passport
  for how to use Telegram Passport properly with python-telegram-bot.
 
+Note:
+To use Telegram Passport, you must install PTB via
+`pip install python-telegram-bot[passport]`
 """
 import logging
 from pathlib import Path
 
+from telegram import __version__ as TG_VER
+
+try:
+    from telegram import __version_info__
+except ImportError:
+    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
+
+if __version_info__ < (20, 0, 0, "alpha", 5):
+    raise RuntimeError(
+        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
+        f"{TG_VER} version of this example, "
+        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
+    )
 from telegram import Update
-from telegram.ext import Application, CallbackContext, MessageHandler, filters
+from telegram.ext import Application, ContextTypes, MessageHandler, filters
 
 # Enable logging
 
@@ -26,7 +42,7 @@ logging.basicConfig(
 logger = logging.getLogger(__name__)
 
 
-async def msg(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def msg(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Downloads and prints the received passport data."""
     # Retrieve passport data
     passport_data = update.message.passport_data
@@ -64,25 +80,25 @@ async def msg(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
             for file in data.files:
                 actual_file = await file.get_file()
                 print(actual_file)
-                await actual_file.download()
+                await actual_file.download_to_drive()
         if (
             data.type in ("passport", "driver_license", "identity_card", "internal_passport")
             and data.front_side
         ):
             front_file = await data.front_side.get_file()
             print(data.type, front_file)
-            await front_file.download()
+            await front_file.download_to_drive()
         if data.type in ("driver_license" and "identity_card") and data.reverse_side:
             reverse_file = await data.reverse_side.get_file()
             print(data.type, reverse_file)
-            await reverse_file.download()
+            await reverse_file.download_to_drive()
         if (
             data.type in ("passport", "driver_license", "identity_card", "internal_passport")
             and data.selfie
         ):
             selfie_file = await data.selfie.get_file()
             print(data.type, selfie_file)
-            await selfie_file.download()
+            await selfie_file.download_to_drive()
         if data.translation and data.type in (
             "passport",
             "driver_license",
@@ -98,7 +114,7 @@ async def msg(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
             for file in data.translation:
                 actual_file = await file.get_file()
                 print(actual_file)
-                await actual_file.download()
+                await actual_file.download_to_drive()
 
 
 def main() -> None:

examples/paymentbot.py

@@ -1,16 +1,29 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument
+# pylint: disable=unused-argument, wrong-import-position
 # This program is dedicated to the public domain under the CC0 license.
 
 """Basic example for a bot that can receive payment from user."""
 
 import logging
 
+from telegram import __version__ as TG_VER
+
+try:
+    from telegram import __version_info__
+except ImportError:
+    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
+
+if __version_info__ < (20, 0, 0, "alpha", 1):
+    raise RuntimeError(
+        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
+        f"{TG_VER} version of this example, "
+        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
+    )
 from telegram import LabeledPrice, ShippingOption, Update
 from telegram.ext import (
     Application,
-    CallbackContext,
     CommandHandler,
+    ContextTypes,
     MessageHandler,
     PreCheckoutQueryHandler,
     ShippingQueryHandler,
@@ -26,7 +39,7 @@ logger = logging.getLogger(__name__)
 PAYMENT_PROVIDER_TOKEN = "PAYMENT_PROVIDER_TOKEN"
 
 
-async def start_callback(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def start_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Displays info on how to use the bot."""
     msg = (
         "Use /shipping to get an invoice for shipping-payment, or /noshipping for an "
@@ -36,9 +49,7 @@ async def start_callback(update: Update, context: CallbackContext.DEFAULT_TYPE)
     await update.message.reply_text(msg)
 
 
-async def start_with_shipping_callback(
-    update: Update, context: CallbackContext.DEFAULT_TYPE
-) -> None:
+async def start_with_shipping_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Sends an invoice with shipping-payment."""
     chat_id = update.message.chat_id
     title = "Payment Example"
@@ -72,7 +83,7 @@ async def start_with_shipping_callback(
 
 
 async def start_without_shipping_callback(
-    update: Update, context: CallbackContext.DEFAULT_TYPE
+    update: Update, context: ContextTypes.DEFAULT_TYPE
 ) -> None:
     """Sends an invoice without shipping-payment."""
     chat_id = update.message.chat_id
@@ -94,7 +105,7 @@ async def start_without_shipping_callback(
     )
 
 
-async def shipping_callback(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def shipping_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Answers the ShippingQuery with ShippingOptions"""
     query = update.shipping_query
     # check the payload, is this from your bot?
@@ -112,7 +123,7 @@ async def shipping_callback(update: Update, context: CallbackContext.DEFAULT_TYP
 
 
 # after (optional) shipping, it's the pre-checkout
-async def precheckout_callback(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def precheckout_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Answers the PreQecheckoutQuery"""
     query = update.pre_checkout_query
     # check the payload, is this from your bot?
@@ -124,9 +135,7 @@ async def precheckout_callback(update: Update, context: CallbackContext.DEFAULT_
 
 
 # finally, after contacting the payment provider...
-async def successful_payment_callback(
-    update: Update, context: CallbackContext.DEFAULT_TYPE
-) -> None:
+async def successful_payment_callback(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Confirms the successful payment."""
     # do something after successfully receiving payment?
     await update.message.reply_text("Thank you for your payment!")

examples/persistentconversationbot.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument
+# pylint: disable=unused-argument, wrong-import-position
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -17,11 +17,24 @@ bot.
 import logging
 from typing import Dict
 
+from telegram import __version__ as TG_VER
+
+try:
+    from telegram import __version_info__
+except ImportError:
+    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
+
+if __version_info__ < (20, 0, 0, "alpha", 1):
+    raise RuntimeError(
+        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
+        f"{TG_VER} version of this example, "
+        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
+    )
 from telegram import ReplyKeyboardMarkup, ReplyKeyboardRemove, Update
 from telegram.ext import (
     Application,
-    CallbackContext,
     CommandHandler,
+    ContextTypes,
     ConversationHandler,
     MessageHandler,
     PicklePersistence,
@@ -50,7 +63,7 @@ def facts_to_str(user_data: Dict[str, str]) -> str:
     return "\n".join(facts).join(["\n", "\n"])
 
 
-async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Start the conversation, display any stored data and ask user for input."""
     reply_text = "Hi! My name is Doctor Botter."
     if context.user_data:
@@ -68,7 +81,7 @@ async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
     return CHOOSING
 
 
-async def regular_choice(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def regular_choice(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Ask the user for info about the selected predefined choice."""
     text = update.message.text.lower()
     context.user_data["choice"] = text
@@ -83,7 +96,7 @@ async def regular_choice(update: Update, context: CallbackContext.DEFAULT_TYPE)
     return TYPING_REPLY
 
 
-async def custom_choice(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def custom_choice(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Ask the user for a description of a custom category."""
     await update.message.reply_text(
         'Alright, please send me the category first, for example "Most impressive skill"'
@@ -92,7 +105,7 @@ async def custom_choice(update: Update, context: CallbackContext.DEFAULT_TYPE) -
     return TYPING_CHOICE
 
 
-async def received_information(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def received_information(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Store info provided by user and ask for the next category."""
     text = update.message.text
     category = context.user_data["choice"]
@@ -109,14 +122,14 @@ async def received_information(update: Update, context: CallbackContext.DEFAULT_
     return CHOOSING
 
 
-async def show_data(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def show_data(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Display the gathered info."""
     await update.message.reply_text(
         f"This is what you already told me: {facts_to_str(context.user_data)}"
     )
 
 
-async def done(update: Update, context: CallbackContext.DEFAULT_TYPE) -> int:
+async def done(update: Update, context: ContextTypes.DEFAULT_TYPE) -> int:
     """Display the gathered info and end the conversation."""
     if "choice" in context.user_data:
         del context.user_data["choice"]

examples/pollbot.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument
+# pylint: disable=unused-argument, wrong-import-position
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -9,6 +9,19 @@ one the user sends the bot
 """
 import logging
 
+from telegram import __version__ as TG_VER
+
+try:
+    from telegram import __version_info__
+except ImportError:
+    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
+
+if __version_info__ < (20, 0, 0, "alpha", 1):
+    raise RuntimeError(
+        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
+        f"{TG_VER} version of this example, "
+        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
+    )
 from telegram import (
     KeyboardButton,
     KeyboardButtonPollType,
@@ -20,8 +33,8 @@ from telegram import (
 from telegram.constants import ParseMode
 from telegram.ext import (
     Application,
-    CallbackContext,
     CommandHandler,
+    ContextTypes,
     MessageHandler,
     PollAnswerHandler,
     PollHandler,
@@ -35,7 +48,7 @@ logging.basicConfig(
 logger = logging.getLogger(__name__)
 
 
-async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Inform user about what this bot can do"""
     await update.message.reply_text(
         "Please select /poll to get a Poll, /quiz to get a Quiz or /preview"
@@ -43,7 +56,7 @@ async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
     )
 
 
-async def poll(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def poll(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Sends a predefined poll"""
     questions = ["Good", "Really good", "Fantastic", "Great"]
     message = await context.bot.send_poll(
@@ -65,7 +78,7 @@ async def poll(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
     context.bot_data.update(payload)
 
 
-async def receive_poll_answer(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def receive_poll_answer(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Summarize a users poll vote"""
     answer = update.poll_answer
     answered_poll = context.bot_data[answer.poll_id]
@@ -92,7 +105,7 @@ async def receive_poll_answer(update: Update, context: CallbackContext.DEFAULT_T
         await context.bot.stop_poll(answered_poll["chat_id"], answered_poll["message_id"])
 
 
-async def quiz(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def quiz(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Send a predefined poll"""
     questions = ["1", "2", "4", "20"]
     message = await update.effective_message.reply_poll(
@@ -105,7 +118,7 @@ async def quiz(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
     context.bot_data.update(payload)
 
 
-async def receive_quiz_answer(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def receive_quiz_answer(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Close quiz after three participants took it"""
     # the bot can receive closed poll updates we don't care about
     if update.poll.is_closed:
@@ -119,7 +132,7 @@ async def receive_quiz_answer(update: Update, context: CallbackContext.DEFAULT_T
         await context.bot.stop_poll(quiz_data["chat_id"], quiz_data["message_id"])
 
 
-async def preview(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def preview(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Ask user to create a poll and display a preview of it"""
     # using this without a type lets the user chooses what he wants (quiz or poll)
     button = [[KeyboardButton("Press me!", request_poll=KeyboardButtonPollType())]]
@@ -130,7 +143,7 @@ async def preview(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None
     )
 
 
-async def receive_poll(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def receive_poll(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """On receiving polls, reply to it by a closed poll copying the received poll"""
     actual_poll = update.effective_message.poll
     # Only need to set the question and options, since all other parameters don't matter for
@@ -144,7 +157,7 @@ async def receive_poll(update: Update, context: CallbackContext.DEFAULT_TYPE) ->
     )
 
 
-async def help_handler(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def help_handler(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Display a help message"""
     await update.message.reply_text("Use /quiz, /poll or /preview to test this bot.")
 

examples/rawapibot.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python
+# pylint: disable=wrong-import-position
 """Simple Bot to reply to Telegram messages.
 
 This is built on the API wrapper, see echobot.py to see the same example built
@@ -9,6 +10,19 @@ import asyncio
 import logging
 from typing import NoReturn
 
+from telegram import __version__ as TG_VER
+
+try:
+    from telegram import __version_info__
+except ImportError:
+    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]  # type: ignore[assignment]
+
+if __version_info__ < (20, 0, 0, "alpha", 1):
+    raise RuntimeError(
+        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
+        f"{TG_VER} version of this example, "
+        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
+    )
 from telegram import Bot
 from telegram.error import Forbidden, NetworkError
 

examples/timerbot.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# pylint: disable=unused-argument
+# pylint: disable=unused-argument, wrong-import-position
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -16,12 +16,29 @@ Usage:
 Basic Alarm Bot example, sends a message after a set time.
 Press Ctrl-C on the command line or send a signal to the process to stop the
 bot.
+
+Note:
+To use arbitrary callback data, you must install ptb via
+`pip install python-telegram-bot[callback-data]`
 """
 
 import logging
 
+from telegram import __version__ as TG_VER
+
+try:
+    from telegram import __version_info__
+except ImportError:
+    __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
+
+if __version_info__ < (20, 0, 0, "alpha", 1):
+    raise RuntimeError(
+        f"This example is not compatible with your current PTB version {TG_VER}. To view the "
+        f"{TG_VER} version of this example, "
+        f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html"
+    )
 from telegram import Update
-from telegram.ext import Application, CallbackContext, CommandHandler
+from telegram.ext import Application, CommandHandler, ContextTypes
 
 # Enable logging
 logging.basicConfig(
@@ -35,18 +52,18 @@ logging.basicConfig(
 # since context is an unused local variable.
 # This being an example and not having context present confusing beginners,
 # we decided to have it present as context.
-async def start(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Sends explanation on how to use the bot."""
     await update.message.reply_text("Hi! Use /set <seconds> to set a timer")
 
 
-async def alarm(context: CallbackContext.DEFAULT_TYPE) -> None:
+async def alarm(context: ContextTypes.DEFAULT_TYPE) -> None:
     """Send the alarm message."""
     job = context.job
-    await context.bot.send_message(job.chat_id, text=f"Beep! {job.context} seconds are over!")
+    await context.bot.send_message(job.chat_id, text=f"Beep! {job.data} seconds are over!")
 
 
-def remove_job_if_exists(name: str, context: CallbackContext.DEFAULT_TYPE) -> bool:
+def remove_job_if_exists(name: str, context: ContextTypes.DEFAULT_TYPE) -> bool:
     """Remove job with given name. Returns whether job was removed."""
     current_jobs = context.job_queue.get_jobs_by_name(name)
     if not current_jobs:
@@ -56,29 +73,29 @@ def remove_job_if_exists(name: str, context: CallbackContext.DEFAULT_TYPE) -> bo
     return True
 
 
-async def set_timer(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def set_timer(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Add a job to the queue."""
     chat_id = update.effective_message.chat_id
     try:
         # args[0] should contain the time for the timer in seconds
-        due = int(context.args[0])
+        due = float(context.args[0])
         if due < 0:
-            await update.message.reply_text("Sorry we can not go back to future!")
+            await update.effective_message.reply_text("Sorry we can not go back to future!")
             return
 
         job_removed = remove_job_if_exists(str(chat_id), context)
-        context.job_queue.run_once(alarm, due, chat_id=chat_id, name=str(chat_id), context=due)
+        context.job_queue.run_once(alarm, due, chat_id=chat_id, name=str(chat_id), data=due)
 
         text = "Timer successfully set!"
         if job_removed:
             text += " Old one was removed."
-        await update.message.reply_text(text)
+        await update.effective_message.reply_text(text)
 
     except (IndexError, ValueError):
         await update.effective_message.reply_text("Usage: /set <seconds>")
 
 
-async def unset(update: Update, context: CallbackContext.DEFAULT_TYPE) -> None:
+async def unset(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
     """Remove the job if the user changed their mind."""
     chat_id = update.message.chat_id
     job_removed = remove_job_if_exists(str(chat_id), context)

examples/webappbot.html

@@ -0,0 +1,39 @@
+<!--
+    Simple static Telegram WebApp. Does not verify the WebAppInitData, as a bot token would be needed for that.
+-->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>python-telegram-bot Example WebApp</title>
+    <script src="https://telegram.org/js/telegram-web-app.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@jaames/iro@5"></script>
+</head>
+<script type="text/javascript">
+    const colorPicker = new iro.ColorPicker('#picker', {
+        borderColor: "#ffffff",
+        borderWidth: 1,
+        width: Math.round(document.documentElement.clientWidth / 2),
+    });
+    colorPicker.on('color:change', function (color) {
+        document.body.style.background = color.hexString;
+    });
+
+    Telegram.WebApp.ready();
+    Telegram.WebApp.MainButton.setText('Choose Color').show().onClick(function () {
+        const data = JSON.stringify({hex: colorPicker.color.hexString, rgb: colorPicker.color.rgb});
+        Telegram.WebApp.sendData(data);
+        Telegram.WebApp.close();
+    });
+</script>
+<body style="background-color: #ffffff">
+<div style="position: absolute; margin-top: 5vh; margin-left: 5vw; height: 90vh; width: 90vw; border-radius: 5vh; background-color: var(--tg-theme-bg-color); box-shadow: 0 0 2vw
+ #000000;">
+    <div id="picker"
+         style="display: flex; justify-content: center; align-items: center; height: 100%; width: 100%"></div>
+</div>
+</body>
+<script type="text/javascript">
+    Telegram.WebApp.expand();
+</script>
+</html>