Bump version to v20.0a5

Co-authored-by: Poolitzer <25934244+Poolitzer@users.noreply.github.com>
Co-authored-by: Hinrich Mahler <22366557+Bibo-Joshi@users.noreply.github.com>
Co-authored-by: Dmitry Kolomatskiy <58207913+lemontree210@users.noreply.github.com>
Co-authored-by: Clot <69784758+clot27@users.noreply.github.com>

.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:
@@ -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
@@ -280,3 +287,4 @@ break the API classes. For example:
 .. _`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/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

@@ -14,22 +14,10 @@ jobs:
   pytest:
     name: pytest
     runs-on: ${{matrix.os}}
-    continue-on-error: ${{ matrix.experimental }}
     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]
-        experimental: [false]
-        include:
-          - python-version: 3.11.0-rc.1
-            os: ubuntu-latest
-            experimental: true
-          - python-version: 3.11.0-rc.1
-            os: windows-latest
-            experimental: true
-          - python-version: 3.11.0-rc.1
-            os: macos-latest
-            experimental: true
       fail-fast: False
     steps:
       - uses: actions/checkout@v3
@@ -42,8 +30,8 @@ jobs:
           python -W ignore -m pip install --upgrade pip
           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-opts.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 4 different suites here
@@ -54,29 +42,49 @@ jobs:
         # 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_PASSPORT='true'
-          pytest -v --cov --cov-append -k test_helpers.py
-          no_pytz_exit=$?
-          export TEST_PYTZ='true'
-          pip uninstall aiolimiter -y
+          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
-          no_rate_limiter_exit=$?
-          export TEST_RATE_LIMITER='true'
+          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
-          pytest -v --cov --cov-append
-          full_exit=$?
-          special_exit=$(( no_pytz_exit > no_passport_exit ? no_pytz_exit : no_passport_exit ))
-          special_exit=$(( special_exit > no_rate_limiter_exit ? special_exit : no_rate_limiter_exit ))
-          global_exit=$(( special_exit > full_exit ? special_exit : full_exit ))
-          exit ${global_exit}
+          # `-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_PYTZ : "false"
-          TEST_PASSPORT: "false"
-          TEST_RATE_LIMITER: "false"
+          BOTS: W3sidG9rZW4iOiAiNjk2MTg4NzMyOkFBR1Z3RUtmSEhsTmpzY3hFRE5LQXdraEdzdFpfa28xbUMwIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6WldGaU1UUmxNbVF5TnpNeSIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gVHJhdmlzIHVzaW5nIENQeXRob24gMi43IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxMzkwOTgzOTk3IiwgImJvdF91c2VybmFtZSI6ICJAcHRiX3RyYXZpc19jcHl0aG9uXzI3X2JvdCJ9LCB7InRva2VuIjogIjY3MTQ2ODg4NjpBQUdQR2ZjaVJJQlVORmU4MjR1SVZkcTdKZTNfWW5BVE5HdyIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOlpHWXdPVGxrTXpNeE4yWTIiLCAiYm90X25hbWUiOiAiUFRCIHRlc3RzIG9uIFRyYXZpcyB1c2luZyBDUHl0aG9uIDMuNCIsICJzdXBlcl9ncm91cF9pZCI6ICItMTAwMTQ0NjAyMjUyMiIsICJib3RfdXNlcm5hbWUiOiAiQHB0Yl90cmF2aXNfY3B5dGhvbl8zNF9ib3QifSwgeyJ0b2tlbiI6ICI2MjkzMjY1Mzg6QUFGUnJaSnJCN29CM211ekdzR0pYVXZHRTVDUXpNNUNVNG8iLCAicGF5bWVudF9wcm92aWRlcl90b2tlbiI6ICIyODQ2ODUwNjM6VEVTVDpNbU01WVdKaFl6a3hNMlUxIiwgImJvdF9uYW1lIjogIlBUQiB0ZXN0cyBvbiBUcmF2aXMgdXNpbmcgQ1B5dGhvbiAzLjUiLCAic3VwZXJfZ3JvdXBfaWQiOiAiLTEwMDE0OTY5MTc3NTAiLCAiYm90X3VzZXJuYW1lIjogIkBwdGJfdHJhdmlzX2NweXRob25fMzVfYm90In0sIHsidG9rZW4iOiAiNjQwMjA4OTQzOkFBRmhCalFwOXFtM1JUeFN6VXBZekJRakNsZS1Kano1aGNrIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6WXpoa1pUZzFOamMxWXpWbCIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gVHJhdmlzIHVzaW5nIENQeXRob24gMy42IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxMzMzODcxNDYxIiwgImJvdF91c2VybmFtZSI6ICJAcHRiX3RyYXZpc19jcHl0aG9uXzM2X2JvdCJ9LCB7InRva2VuIjogIjY5NTEwNDA4ODpBQUhmenlsSU9qU0lJUy1lT25JMjB5MkUyMEhvZEhzZnotMCIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOk9HUTFNRGd3WmpJd1pqRmwiLCAiYm90X25hbWUiOiAiUFRCIHRlc3RzIG9uIFRyYXZpcyB1c2luZyBDUHl0aG9uIDMuNyIsICJzdXBlcl9ncm91cF9pZCI6ICItMTAwMTQ3ODI5MzcxNCIsICJib3RfdXNlcm5hbWUiOiAiQHB0Yl90cmF2aXNfY3B5dGhvbl8zN19ib3QifSwgeyJ0b2tlbiI6ICI2OTE0MjM1NTQ6QUFGOFdrakNaYm5IcVBfaTZHaFRZaXJGRWxackdhWU9oWDAiLCAicGF5bWVudF9wcm92aWRlcl90b2tlbiI6ICIyODQ2ODUwNjM6VEVTVDpZamM1TlRoaU1tUXlNV1ZoIiwgImJvdF9uYW1lIjogIlBUQiB0ZXN0cyBvbiBUcmF2aXMgdXNpbmcgUHlQeSAyLjciLCAic3VwZXJfZ3JvdXBfaWQiOiAiLTEwMDEzNjM5MzI1NzMiLCAiYm90X3VzZXJuYW1lIjogIkBwdGJfdHJhdmlzX3B5cHlfMjdfYm90In0sIHsidG9rZW4iOiAiNjg0MzM5OTg0OkFBRk1nRUVqcDAxcjVyQjAwN3lDZFZOc2c4QWxOc2FVLWNjIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6TVRBek1UWTNNR1V5TmpnMCIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gVHJhdmlzIHVzaW5nIFB5UHkgMy41IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxNDA3ODM2NjA1IiwgImJvdF91c2VybmFtZSI6ICJAcHRiX3RyYXZpc19weXB5XzM1X2JvdCJ9LCB7InRva2VuIjogIjY5MDA5MTM0NzpBQUZMbVI1cEFCNVljcGVfbU9oN3pNNEpGQk9oMHozVDBUbyIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOlpEaGxOekU1TURrd1lXSmkiLCAiYm90X25hbWUiOiAiUFRCIHRlc3RzIG9uIEFwcFZleW9yIHVzaW5nIENQeXRob24gMy40IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxMjc5NjAwMDI2IiwgImJvdF91c2VybmFtZSI6ICJAcHRiX2FwcHZleW9yX2NweXRob25fMzRfYm90In0sIHsidG9rZW4iOiAiNjk0MzA4MDUyOkFBRUIyX3NvbkNrNTVMWTlCRzlBTy1IOGp4aVBTNTVvb0JBIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6WW1aaVlXWm1NakpoWkdNeSIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gQXBwVmV5b3IgdXNpbmcgQ1B5dGhvbiAyLjciLCAic3VwZXJfZ3JvdXBfaWQiOiAiLTEwMDEyOTMwNzkxNjUiLCAiYm90X3VzZXJuYW1lIjogIkBwdGJfYXBwdmV5b3JfY3B5dGhvbl8yN19ib3QifSwgeyJ0b2tlbiI6ICIxMDU1Mzk3NDcxOkFBRzE4bkJfUzJXQXd1SjNnN29oS0JWZ1hYY2VNbklPeVNjIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6TmpBd056QXpZalZpTkdOayIsICJuYW1lIjogIlBUQiB0ZXN0cyBbMF0iLCAic3VwZXJfZ3JvdXBfaWQiOiAiLTEwMDExODU1MDk2MzYiLCAidXNlcm5hbWUiOiAicHRiXzBfYm90In0sIHsidG9rZW4iOiAiMTA0NzMyNjc3MTpBQUY4bk90ODFGcFg4bGJidno4VWV3UVF2UmZUYkZmQnZ1SSIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOllUVTFOVEk0WkdSallqbGkiLCAibmFtZSI6ICJQVEIgdGVzdHMgWzFdIiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxNDg0Nzk3NjEyIiwgInVzZXJuYW1lIjogInB0Yl8xX2JvdCJ9LCB7InRva2VuIjogIjk3MTk5Mjc0NTpBQUdPa09hVzBOSGpnSXY1LTlqUWJPajR2R3FkaFNGLVV1cyIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOk5XWmtNV1ZoWWpsallqVTUiLCAibmFtZSI6ICJQVEIgdGVzdHMgWzJdIiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxNDAyMjU1MDcwIiwgInVzZXJuYW1lIjogInB0Yl8yX2JvdCJ9LCB7InRva2VuIjogIjU1MTg2NDU0MTE6QUFHdzBxaEs3ZTRHbmoxWjJjc1BBQzdaYWtvTWs1NkVKZmsiLCAicGF5bWVudF9wcm92aWRlcl90b2tlbiI6ICIyODQ2ODUwNjM6VEVTVDpNRE0wT1RCbE9UUXpNVEU1IiwgIm5hbWUiOiAiUFRCIFRlc3QgQm90IFszXSIsICJzdXBlcl9ncm91cF9pZCI6ICItMTAwMTgwMzgxMDE5NiIsICJ1c2VybmFtZSI6ICJwdGJfdGVzdF8wM19ib3QifSwgeyJ0b2tlbiI6ICI1NzM3MDE4MzU2OkFBSDEzOFN1aUtRRjBMRENXc2ZnV2VYZmpKNWQ2M2tDV0xBIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6TjJWaVpqUmxaak01TlRNdyIsICJuYW1lIjogIlBUQiBUZXN0IEJvdCBbNF0iLCAidXNlcm5hbWUiOiAicHRiX3Rlc3RfMDRfYm90IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxODQyNDM5NjQxIn0sIHsidG9rZW4iOiAiNTc0NDY0NDUyMjpBQUVBZHNyRjBoQzZwNkhVTzBQMDFROGJfakNoVTUyWEctTSIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOlpqSmtZVGd5TmpnMlpHRTAiLCAibmFtZSI6ICJQVEIgVGVzdCBCb3QgWzVdIiwgInVzZXJuYW1lIjogInB0Yl90ZXN0XzA1X2JvdCIsICJzdXBlcl9ncm91cF9pZCI6ICItMTAwMTg1NTM2MDk4NiJ9XQ==
+          TEST_WITH_OPT_DEPS : "false"
           TEST_BUILD: "true"
         shell: bash --noprofile --norc {0}
 

.pre-commit-config.yaml

@@ -9,18 +9,18 @@ ci:
 
 repos:
 -   repo: https://github.com/psf/black
-    rev: 22.6.0
+    rev: 22.10.0
     hooks:
     -   id: black
         args:
         - --diff
         - --check
 -   repo: https://github.com/PyCQA/flake8
-    rev: 5.0.2
+    rev: 5.0.4
     hooks:
     -   id: flake8
 -   repo: https://github.com/PyCQA/pylint
-    rev: v2.13.9
+    rev: v2.15.5
     hooks:
     -   id: pylint
         files: ^(telegram|examples)/.*\.py$
@@ -38,7 +38,7 @@ repos:
           - aiolimiter~=1.0.0
           - . # this basically does `pip install -e .`
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.971
+    rev: v0.982
     hooks:
     -   id: mypy
         name: mypy-ptb
@@ -65,7 +65,7 @@ repos:
         - cachetools~=5.2.0
         - . # this basically does `pip install -e .`
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v2.37.3
+    rev: v3.2.0
     hooks:
     -   id: pyupgrade
         files: ^(telegram|examples|tests)/.*\.py$

.readthedocs.yml

@@ -21,6 +21,31 @@ python:
      - requirements: docs/requirements-docs.txt
 
 build:
-   os: ubuntu-20.04
+   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,6 +30,7 @@ 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>`_
@@ -72,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>`_

CHANGES.rst

@@ -2,6 +2,169 @@
 Changelog
 =========
 
+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*

MANIFEST.in

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

README.rst

@@ -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.2-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
 
@@ -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.23.0 <https://www.python-httpx.org>`_ for ``telegram.request.HTTPXRequest``, the default networking backend
-* `tornado~=6.2 <https://www.tornadoweb.org/en/stable/>`_ for ``telegram.ext.Updater.start_webhook``
-* `cachetools~=5.2.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/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
 ===========

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.2-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
 
@@ -120,22 +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.23.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/en/stable>`_ library. Use this, if you want to use Telegram Passport related functionality.
-* ``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
 ===========

docs/requirements-docs.txt

@@ -1,5 +1,6 @@
-sphinx==5.1.1
+sphinx==5.3.0
 sphinx-pypi-upload
-furo==2022.6.21
+furo==2022.9.29
+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/conf.py

@@ -5,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
@@ -29,12 +29,12 @@ author = "Leandro Toledo"
 # built documents.
 #
 # The short X.Y version.
-version = "20.0a3"  # telegram.__version__[:3]
+version = "20.0a5"  # telegram.__version__[:3]
 # The full version, including alpha/beta/rc tags.
-release = "20.0a3"  # telegram.__version__
+release = "20.0a5"  # 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
@@ -46,6 +46,7 @@ extensions = [
     "sphinx.ext.linkcode",
     "sphinx_paramlinks",
     "sphinxcontrib.mermaid",
+    "sphinx_search.extension",
 ]
 
 # Use intersphinx to reference the python builtin library docs
@@ -64,6 +65,9 @@ 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
 
@@ -212,11 +216,9 @@ 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_permalinks_icon = "¶"  # Furo's default permalink icon is `#`` which doesn't look great imo.
+html_css_files = ["style_external_link.css", "style_mermaid_diagrams.css"]
+
+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"
@@ -257,6 +259,7 @@ latex_logo = "ptb-logo_1024.png"
 # (source start file, name, description, authors, manual section).
 man_pages = [(master_doc, "python-telegram-bot", "python-telegram-bot Documentation", [author], 1)]
 
+# rtd_sphinx_search_file_type = "un-minified"  # Configuration for furo-sphinx-search
 
 # -- Options for Texinfo output -------------------------------------------
 
@@ -292,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.
     """
 
@@ -375,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

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

@@ -256,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>
@@ -290,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`
@@ -304,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/telegram.at-tree.rst

@@ -0,0 +1,86 @@
+Available Types
+---------------
+
+.. toctree::
+
+    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.extbot.rst

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

docs/source/telegram.ext.rst

@@ -2,6 +2,7 @@ telegram.ext package
 ====================
 
 .. toctree::
+    :titlesonly:
 
     telegram.ext.application
     telegram.ext.applicationbuilder

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

@@ -7,88 +7,14 @@ Version Constants
 .. automodule:: telegram
    :members: __version__, __version_info__, __bot_api_version__, __bot_api_version_info__
 
-Available Types
----------------
+Classes in this package
+-----------------------
 
 .. toctree::
+    :titlesonly:
 
-    telegram.animation
-    telegram.audio
     telegram.bot
-    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.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
+    telegram.at-tree.rst
     telegram.stickers-tree.rst
     telegram.inline-tree.rst
     telegram.payments-tree.rst

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__

docs/substitutions/global.rst

@@ -0,0 +1,43 @@
+.. |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.

examples/conversationbot.py

@@ -23,7 +23,7 @@ try:
 except ImportError:
     __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
 
-if __version_info__ < (20, 0, 0, "alpha", 1):
+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, "
@@ -81,7 +81,7 @@ 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_memory("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."

examples/deeplinking.py

@@ -115,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/passportbot.py

@@ -21,7 +21,7 @@ try:
 except ImportError:
     __version_info__ = (0, 0, 0, 0, 0)  # type: ignore[assignment]
 
-if __version_info__ < (20, 0, 0, "alpha", 1):
+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, "
@@ -77,25 +77,25 @@ async def msg(update: Update, context: ContextTypes.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_memory()
         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_memory()
         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_memory()
         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_memory()
         if data.translation and data.type in (
             "passport",
             "driver_license",
@@ -111,7 +111,7 @@ async def msg(update: Update, context: ContextTypes.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_memory()
 
 
 def main() -> None:

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.black]
 line-length = 99
-target-version = ['py37', 'py38', 'py39', 'py310']
+target-version = ['py37', 'py38', 'py39', 'py310', 'py311']
 
 [tool.isort]  # black config
 profile = "black"

requirements-dev.txt

@@ -1,8 +1,9 @@
 pre-commit
 
-pytest==7.1.2
-pytest-asyncio==0.19.0
+pytest==7.2.0
+pytest-asyncio==0.20.2
 pytest-timeout==2.1.0 # used to timeout tests
+pytest-xdist==3.0.2  # xdist runs tests in parallel
 
 flaky  # Used for flaky tests (flaky decorator)
 beautifulsoup4  # used in test_official for parsing tg docs

requirements-opts.txt

@@ -2,6 +2,25 @@
 # package_name==version # req-1, req-2, req-3!ext
 # `pip install ptb-raw[req-1/2]` will install `package_name`
 # `pip install ptb[req-1/2/3]` will also install `package_name`
+
+# Make sure to install those as additional_dependencies in the
+# pre-commit hooks for pylint & mypy
+# Also update the readme accordingly
+
+# When dependencies release new versions and tests succeed, we should try to expand the allowed
+# versions and only increase the lower bound if necessary
+
 httpx[socks] # socks
 cryptography!=3.4,!=3.4.1,!=3.4.2,!=3.4.3,>=3.0 # passport
-aiolimiter~=1.0.0 # rate-limiter!ext
+aiolimiter~=1.0.0 # rate-limiter!ext
+
+# tornado is rather stable, but let's not allow the next mayor release without prior testing
+tornado~=6.2 # webhooks!ext
+
+# Cachetools and APS don't have a strict stability policy.
+# Let's be cautious for now.
+cachetools~=5.2.0 # callback-data!ext
+APScheduler~=3.9.1 # job-queue!ext
+
+# pytz is required by APS and just needs the lower bound due to #2120
+pytz>=2018.6 # job-queue!ext

requirements.txt

@@ -6,16 +6,4 @@
 # versions and only increase the lower bound if necessary
 
 # httpx has no stable release yet, so let's be cautious for now
-httpx ~= 0.23.0
-# only telegram.ext: # Keep this line here; used in setup(-raw).py
-
-# tornado is rather stable, but let's not allow the next mayor release without prior testing
-tornado~=6.2
-
-# Cachetools and APS don't have a strict stability policy.
-# Let's be cautious for now.
-cachetools~=5.2.0
-APScheduler~=3.9.1
-
-# pytz is required by APS and just needs the lower bound due to #2120
-pytz>=2018.6
+httpx ~= 0.23.1

setup.cfg

@@ -1,5 +1,5 @@
 [metadata]
-license_file = LICENSE.dual
+license_files = LICENSE, LICENSE.dual, LICENSE.lesser
 
 [build_sphinx]
 source-dir = docs/source

setup.py

@@ -8,15 +8,13 @@ from pathlib import Path
 from setuptools import find_packages, setup
 
 
-def get_requirements(raw=False):
+def get_requirements():
     """Build the requirements list for this project"""
     requirements_list = []
 
     with Path("requirements.txt").open() as reqs:
         for install in reqs:
-            if install.startswith("# only telegram.ext:"):
-                if raw:
-                    break
+            if install.startswith("#"):
                 continue
             requirements_list.append(install.strip())
 
@@ -25,7 +23,7 @@ def get_requirements(raw=False):
 
 def get_packages_requirements(raw=False):
     """Build the package & requirements list for this project"""
-    reqs = get_requirements(raw=raw)
+    reqs = get_requirements()
 
     exclude = ["tests*"]
     if raw:
@@ -42,15 +40,21 @@ def get_optional_requirements(raw=False):
 
     with Path("requirements-opts.txt").open() as reqs:
         for line in reqs:
-            if line.startswith("#"):
+            line = line.strip()
+            if not line or line.startswith("#"):
                 continue
             dependency, names = line.split("#")
             dependency = dependency.strip()
             for name in names.split(","):
                 name = name.strip()
-                if name.endswith("!ext") and raw:
-                    continue
+                if name.endswith("!ext"):
+                    if raw:
+                        continue
+                    else:
+                        name = name[:-4]
+                        requirements["ext"].append(dependency)
                 requirements[name].append(dependency)
+                requirements["all"].append(dependency)
 
     return requirements
 

telegram/__init__.py

@@ -67,6 +67,10 @@ __all__ = (  # Keep this alphabetically ordered
     "File",
     "FileCredentials",
     "ForceReply",
+    "ForumTopic",
+    "ForumTopicClosed",
+    "ForumTopicCreated",
+    "ForumTopicReopened",
     "Game",
     "GameHighScore",
     "helpers",
@@ -175,7 +179,7 @@ __all__ = (  # Keep this alphabetically ordered
 )
 
 
-from . import _version
+from . import _version, constants, error, helpers, request, warnings
 from ._bot import Bot
 from ._botcommand import BotCommand
 from ._botcommandscope import (
@@ -230,6 +234,7 @@ from ._files.video import Video
 from ._files.videonote import VideoNote
 from ._files.voice import Voice
 from ._forcereply import ForceReply
+from ._forumtopic import ForumTopic, ForumTopicClosed, ForumTopicCreated, ForumTopicReopened
 from ._games.callbackgame import CallbackGame
 from ._games.game import Game
 from ._games.gamehighscore import GameHighScore
@@ -312,6 +317,15 @@ from ._telegramobject import TelegramObject
 from ._update import Update
 from ._user import User
 from ._userprofilephotos import UserProfilePhotos
+from ._videochat import (
+    VideoChatEnded,
+    VideoChatParticipantsInvited,
+    VideoChatScheduled,
+    VideoChatStarted,
+)
+from ._webappdata import WebAppData
+from ._webappinfo import WebAppInfo
+from ._webhookinfo import WebhookInfo
 
 #: :obj:`str`: The version of the `python-telegram-bot` library as string.
 #: To get detailed information about the version number, please use :data:`__version_info__`
@@ -335,13 +349,3 @@ __bot_api_version__ = _version.__bot_api_version__
 #:
 #: .. versionadded:: 20.0
 __bot_api_version_info__ = _version.__bot_api_version_info__
-
-from ._videochat import (
-    VideoChatEnded,
-    VideoChatParticipantsInvited,
-    VideoChatScheduled,
-    VideoChatStarted,
-)
-from ._webappdata import WebAppData
-from ._webappinfo import WebAppInfo
-from ._webhookinfo import WebhookInfo

telegram/_botcommand.py

@@ -17,9 +17,12 @@
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram Bot Command."""
-from typing import Any
 
+from typing import ClassVar
+
+from telegram import constants
 from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
 
 
 class BotCommand(TelegramObject):
@@ -30,9 +33,12 @@ class BotCommand(TelegramObject):
     considered equal, if their :attr:`command` and :attr:`description` are equal.
 
     Args:
-        command (:obj:`str`): Text of the command; 1-32 characters. Can contain only lowercase
+        command (:obj:`str`): Text of the command; :tg-const:`telegram.BotCommand.MIN_COMMAND`-
+            :tg-const:`telegram.BotCommand.MAX_COMMAND` characters. Can contain only lowercase
             English letters, digits and underscores.
-        description (:obj:`str`): Description of the command; 1-256 characters.
+        description (:obj:`str`): Description of the command;
+            :tg-const:`telegram.BotCommand.MIN_DESCRIPTION`-
+            :tg-const:`telegram.BotCommand.MAX_DESCRIPTION` characters.
 
     Attributes:
         command (:obj:`str`): Text of the command.
@@ -42,8 +48,30 @@ class BotCommand(TelegramObject):
 
     __slots__ = ("description", "command")
 
-    def __init__(self, command: str, description: str, **_kwargs: Any):
+    def __init__(self, command: str, description: str, *, api_kwargs: JSONDict = None):
+        super().__init__(api_kwargs=api_kwargs)
         self.command = command
         self.description = description
 
         self._id_attrs = (self.command, self.description)
+
+    MIN_COMMAND: ClassVar[int] = constants.BotCommandLimit.MIN_COMMAND
+    """:const:`telegram.constants.BotCommandLimit.MIN_COMMAND`
+
+    .. versionadded:: 20.0
+    """
+    MAX_COMMAND: ClassVar[int] = constants.BotCommandLimit.MAX_COMMAND
+    """:const:`telegram.constants.BotCommandLimit.MAX_COMMAND`
+
+    .. versionadded:: 20.0
+    """
+    MIN_DESCRIPTION: ClassVar[int] = constants.BotCommandLimit.MIN_DESCRIPTION
+    """:const:`telegram.constants.BotCommandLimit.MIN_DESCRIPTION`
+
+    .. versionadded:: 20.0
+    """
+    MAX_DESCRIPTION: ClassVar[int] = constants.BotCommandLimit.MAX_DESCRIPTION
+    """:const:`telegram.constants.BotCommandLimit.MAX_DESCRIPTION`
+
+    .. versionadded:: 20.0
+    """

telegram/_botcommandscope.py

@@ -18,7 +18,7 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 # pylint: disable=redefined-builtin
 """This module contains objects representing Telegram bot command scopes."""
-from typing import TYPE_CHECKING, Any, ClassVar, Dict, Optional, Type, Union
+from typing import TYPE_CHECKING, ClassVar, Dict, Optional, Type, Union
 
 from telegram import constants
 from telegram._telegramobject import TelegramObject
@@ -75,7 +75,8 @@ class BotCommandScope(TelegramObject):
     CHAT_MEMBER: ClassVar[str] = constants.BotCommandScopeType.CHAT_MEMBER
     """:const:`telegram.constants.BotCommandScopeType.CHAT_MEMBER`"""
 
-    def __init__(self, type: str, **_kwargs: Any):
+    def __init__(self, type: str, *, api_kwargs: JSONDict = None):
+        super().__init__(api_kwargs=api_kwargs)
         self.type = type
         self._id_attrs = (self.type,)
 
@@ -107,9 +108,9 @@ class BotCommandScope(TelegramObject):
             cls.CHAT_MEMBER: BotCommandScopeChatMember,
         }
 
-        if cls is BotCommandScope:
-            return _class_mapping.get(data["type"], cls)(**data, bot=bot)
-        return cls(**data)
+        if cls is BotCommandScope and data.get("type") in _class_mapping:
+            return _class_mapping[data.pop("type")].de_json(data=data, bot=bot)
+        return super().de_json(data=data, bot=bot)
 
 
 class BotCommandScopeDefault(BotCommandScope):
@@ -119,15 +120,14 @@ class BotCommandScopeDefault(BotCommandScope):
     .. _`narrower scope`: https://core.telegram.org/bots/api#determining-list-of-commands
 
     .. versionadded:: 13.7
-
     Attributes:
         type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.DEFAULT`.
     """
 
     __slots__ = ()
 
-    def __init__(self, **_kwargs: Any):
-        super().__init__(type=BotCommandScope.DEFAULT)
+    def __init__(self, *, api_kwargs: JSONDict = None):
+        super().__init__(type=BotCommandScope.DEFAULT, api_kwargs=api_kwargs)
 
 
 class BotCommandScopeAllPrivateChats(BotCommandScope):
@@ -141,38 +141,36 @@ class BotCommandScopeAllPrivateChats(BotCommandScope):
 
     __slots__ = ()
 
-    def __init__(self, **_kwargs: Any):
-        super().__init__(type=BotCommandScope.ALL_PRIVATE_CHATS)
+    def __init__(self, *, api_kwargs: JSONDict = None):
+        super().__init__(type=BotCommandScope.ALL_PRIVATE_CHATS, api_kwargs=api_kwargs)
 
 
 class BotCommandScopeAllGroupChats(BotCommandScope):
     """Represents the scope of bot commands, covering all group and supergroup chats.
 
     .. versionadded:: 13.7
-
     Attributes:
         type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.ALL_GROUP_CHATS`.
     """
 
     __slots__ = ()
 
-    def __init__(self, **_kwargs: Any):
-        super().__init__(type=BotCommandScope.ALL_GROUP_CHATS)
+    def __init__(self, *, api_kwargs: JSONDict = None):
+        super().__init__(type=BotCommandScope.ALL_GROUP_CHATS, api_kwargs=api_kwargs)
 
 
 class BotCommandScopeAllChatAdministrators(BotCommandScope):
     """Represents the scope of bot commands, covering all group and supergroup chat administrators.
 
     .. versionadded:: 13.7
-
     Attributes:
         type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.ALL_CHAT_ADMINISTRATORS`.
     """
 
     __slots__ = ()
 
-    def __init__(self, **_kwargs: Any):
-        super().__init__(type=BotCommandScope.ALL_CHAT_ADMINISTRATORS)
+    def __init__(self, *, api_kwargs: JSONDict = None):
+        super().__init__(type=BotCommandScope.ALL_CHAT_ADMINISTRATORS, api_kwargs=api_kwargs)
 
 
 class BotCommandScopeChat(BotCommandScope):
@@ -184,19 +182,17 @@ class BotCommandScopeChat(BotCommandScope):
     .. versionadded:: 13.7
 
     Args:
-        chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the
-            target supergroup (in the format ``@supergroupusername``)
+        chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
 
     Attributes:
         type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.CHAT`.
-        chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the
-            target supergroup (in the format ``@supergroupusername``)
+        chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
     """
 
     __slots__ = ("chat_id",)
 
-    def __init__(self, chat_id: Union[str, int], **_kwargs: Any):
-        super().__init__(type=BotCommandScope.CHAT)
+    def __init__(self, chat_id: Union[str, int], *, api_kwargs: JSONDict = None):
+        super().__init__(type=BotCommandScope.CHAT, api_kwargs=api_kwargs)
         self.chat_id = (
             chat_id if isinstance(chat_id, str) and chat_id.startswith("@") else int(chat_id)
         )
@@ -213,19 +209,16 @@ class BotCommandScopeChatAdministrators(BotCommandScope):
     .. versionadded:: 13.7
 
     Args:
-        chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the
-            target supergroup (in the format ``@supergroupusername``)
-
+        chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
     Attributes:
         type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.CHAT_ADMINISTRATORS`.
-        chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the
-            target supergroup (in the format ``@supergroupusername``)
+        chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
     """
 
     __slots__ = ("chat_id",)
 
-    def __init__(self, chat_id: Union[str, int], **_kwargs: Any):
-        super().__init__(type=BotCommandScope.CHAT_ADMINISTRATORS)
+    def __init__(self, chat_id: Union[str, int], *, api_kwargs: JSONDict = None):
+        super().__init__(type=BotCommandScope.CHAT_ADMINISTRATORS, api_kwargs=api_kwargs)
         self.chat_id = (
             chat_id if isinstance(chat_id, str) and chat_id.startswith("@") else int(chat_id)
         )
@@ -242,21 +235,19 @@ class BotCommandScopeChatMember(BotCommandScope):
     .. versionadded:: 13.7
 
     Args:
-        chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the
-            target supergroup (in the format ``@supergroupusername``)
+        chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
         user_id (:obj:`int`): Unique identifier of the target user.
 
     Attributes:
         type (:obj:`str`): Scope type :tg-const:`telegram.BotCommandScope.CHAT_MEMBER`.
-        chat_id (:obj:`str` | :obj:`int`): Unique identifier for the target chat or username of the
-            target supergroup (in the format ``@supergroupusername``)
+        chat_id (:obj:`str` | :obj:`int`): |chat_id_group|
         user_id (:obj:`int`): Unique identifier of the target user.
     """
 
     __slots__ = ("chat_id", "user_id")
 
-    def __init__(self, chat_id: Union[str, int], user_id: int, **_kwargs: Any):
-        super().__init__(type=BotCommandScope.CHAT_MEMBER)
+    def __init__(self, chat_id: Union[str, int], user_id: int, *, api_kwargs: JSONDict = None):
+        super().__init__(type=BotCommandScope.CHAT_MEMBER, api_kwargs=api_kwargs)
         self.chat_id = (
             chat_id if isinstance(chat_id, str) and chat_id.startswith("@") else int(chat_id)
         )

telegram/_callbackquery.py

@@ -18,7 +18,7 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 # pylint: disable=redefined-builtin
 """This module contains an object that represents a Telegram CallbackQuery"""
-from typing import TYPE_CHECKING, Any, ClassVar, List, Optional, Tuple, Union
+from typing import TYPE_CHECKING, ClassVar, List, Optional, Tuple, Union
 
 from telegram import constants
 from telegram._files.location import Location
@@ -57,7 +57,7 @@ class CallbackQuery(TelegramObject):
           until you call :attr:`answer`. It is, therefore, necessary to react
           by calling :attr:`telegram.Bot.answer_callback_query` even if no notification to the user
           is needed (e.g., without specifying any of the optional parameters).
-        * If you're using :attr:`telegram.ext.ExtBot.arbitrary_callback_data`, :attr:`data` may be
+        * If you're using :attr:`telegram.ext.ExtBot.callback_data_cache`, :attr:`data` may be
           an instance
           of :class:`telegram.ext.InvalidCallbackData`. This will be the case, if the data
           associated with the button triggering the :class:`telegram.CallbackQuery` was already
@@ -79,7 +79,6 @@ class CallbackQuery(TelegramObject):
             inline mode, that originated the query.
         game_short_name (:obj:`str`, optional): Short name of a Game to be returned, serves as
             the unique identifier for the game
-        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
 
     Attributes:
         id (:obj:`str`): Unique identifier for this query.
@@ -96,7 +95,7 @@ class CallbackQuery(TelegramObject):
         inline_message_id (:obj:`str`): Optional. Identifier of the message sent via the bot in
                 inline mode, that originated the query.
         game_short_name (:obj:`str`): Optional. Short name of a Game to be returned.
-        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
+
 
     """
 
@@ -112,16 +111,17 @@ class CallbackQuery(TelegramObject):
 
     def __init__(
         self,
-        id: str,  # pylint: disable=invalid-name
+        id: str,
         from_user: User,
         chat_instance: str,
         message: Message = None,
         data: str = None,
         inline_message_id: str = None,
         game_short_name: str = None,
-        bot: "Bot" = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
         # Required
         self.id = id  # pylint: disable=invalid-name
         self.from_user = from_user
@@ -132,8 +132,6 @@ class CallbackQuery(TelegramObject):
         self.inline_message_id = inline_message_id
         self.game_short_name = game_short_name
 
-        self.set_bot(bot)
-
         self._id_attrs = (self.id,)
 
     @classmethod
@@ -144,10 +142,10 @@ class CallbackQuery(TelegramObject):
         if not data:
             return None
 
-        data["from_user"] = User.de_json(data.get("from"), bot)
+        data["from_user"] = User.de_json(data.pop("from", None), bot)
         data["message"] = Message.de_json(data.get("message"), bot)
 
-        return cls(bot=bot, **data)
+        return super().de_json(data=data, bot=bot)
 
     async def answer(
         self,
@@ -726,6 +724,7 @@ class CallbackQuery(TelegramObject):
         allow_sending_without_reply: DVInput[bool] = DEFAULT_NONE,
         reply_markup: ReplyMarkup = None,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -763,6 +762,7 @@ class CallbackQuery(TelegramObject):
             pool_timeout=pool_timeout,
             api_kwargs=api_kwargs,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
         )
 
     MAX_ANSWER_TEXT_LENGTH: ClassVar[

telegram/_chat.py

@@ -19,7 +19,8 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram Chat."""
 from datetime import datetime
-from typing import TYPE_CHECKING, Any, ClassVar, List, Optional, Tuple, Union
+from html import escape
+from typing import TYPE_CHECKING, ClassVar, List, Optional, Tuple, Union
 
 from telegram import constants
 from telegram._chatlocation import ChatLocation
@@ -30,6 +31,9 @@ from telegram._telegramobject import TelegramObject
 from telegram._utils import enum
 from telegram._utils.defaultvalue import DEFAULT_NONE
 from telegram._utils.types import DVInput, FileInput, JSONDict, ODVInput, ReplyMarkup
+from telegram.helpers import escape_markdown
+from telegram.helpers import mention_html as helpers_mention_html
+from telegram.helpers import mention_markdown as helpers_mention_markdown
 
 if TYPE_CHECKING:
     from telegram import (
@@ -73,6 +77,11 @@ class Chat(TelegramObject):
           ``api_kwargs``. Use a named argument for those,
           and notice that some positional arguments changed position as a result.
 
+    .. versionchanged:: 20.0
+        Removed the attribute ``all_members_are_administrators``. As long as Telegram provides
+        this field for backwards compatibility, it is available through
+        :attr:`~telegram.TelegramObject.api_kwargs`.
+
     Args:
         id (:obj:`int`): Unique identifier for this chat. This number may be greater than 32 bits
             and some programming languages may have difficulty/silent defects in interpreting it.
@@ -114,7 +123,7 @@ class Chat(TelegramObject):
             be forwarded to other chats. Returned only in :meth:`telegram.Bot.get_chat`.
 
             .. versionadded:: 13.9
-        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
+
         sticker_set_name (:obj:`str`, optional): For supergroups, name of group sticker set.
             Returned only in :meth:`telegram.Bot.get_chat`.
         can_set_sticker_set (:obj:`bool`, optional): :obj:`True`, if the bot can change group the
@@ -139,25 +148,45 @@ class Chat(TelegramObject):
             in the private chat. Returned only in :meth:`telegram.Bot.get_chat`.
 
             .. versionadded:: 20.0
+        is_forum (:obj:`bool`, optional): :obj:`True`, if the supergroup chat is a forum
+            (has topics_ enabled).
 
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+            .. versionadded:: 20.0
+        active_usernames (List[:obj:`str`], optional):  If set, the list of all `active chat
+            usernames <https://telegram.org/blog/topics-in-groups-collectible-usernames\
+            #collectible-usernames>`_; for private chats, supergroups and channels. Returned
+            only in :meth:`telegram.Bot.get_chat`.
+
+            .. versionadded:: 20.0
+        emoji_status_custom_emoji_id (:obj:`str`, optional): Custom emoji identifier of emoji
+            status of the other party in a private chat. Returned only in
+            :meth:`telegram.Bot.get_chat`.
+
+            .. versionadded:: 20.0
 
     Attributes:
-        id (:obj:`int`): Unique identifier for this chat.
-        type (:obj:`str`): Type of chat.
+        id (:obj:`int`): Unique identifier for this chat. This number may be greater than 32 bits
+            and some programming languages may have difficulty/silent defects in interpreting it.
+            But it is smaller than 52 bits, so a signed 64-bit integer or double-precision float
+            type are safe for storing this identifier.
+        type (:obj:`str`): Type of chat, can be either :attr:`PRIVATE`, :attr:`GROUP`,
+            :attr:`SUPERGROUP` or :attr:`CHANNEL`.
         title (:obj:`str`): Optional. Title, for supergroups, channels and group chats.
-        username (:obj:`str`): Optional. Username.
+        username (:obj:`str`): Optional. Username, for private chats, supergroups and channels if
+            available.
         first_name (:obj:`str`): Optional. First name of the other party in a private chat.
         last_name (:obj:`str`): Optional. Last name of the other party in a private chat.
         photo (:class:`telegram.ChatPhoto`): Optional. Chat photo.
+            Returned only in :meth:`telegram.Bot.get_chat`.
         bio (:obj:`str`): Optional. Bio of the other party in a private chat. Returned only in
             :meth:`telegram.Bot.get_chat`.
         has_private_forwards (:obj:`bool`): Optional. :obj:`True`, if privacy settings of the other
             party in the private chat allows to use ``tg://user?id=<user_id>`` links only in chats
-            with the user.
+            with the user. Returned only in :meth:`telegram.Bot.get_chat`.
 
             .. versionadded:: 13.9
         description (:obj:`str`): Optional. Description, for groups, supergroups and channel chats.
+            Returned only in :meth:`telegram.Bot.get_chat`.
         invite_link (:obj:`str`): Optional. Primary invite link, for groups, supergroups and
             channel. Returned only in :meth:`telegram.Bot.get_chat`.
         pinned_message (:class:`telegram.Message`): Optional. The most recent pinned message
@@ -173,12 +202,13 @@ class Chat(TelegramObject):
 
             .. versionadded:: 13.4
         has_protected_content (:obj:`bool`): Optional. :obj:`True`, if messages from the chat can't
-            be forwarded to other chats.
+            be forwarded to other chats. Returned only in :meth:`telegram.Bot.get_chat`.
 
             .. versionadded:: 13.9
         sticker_set_name (:obj:`str`): Optional. For supergroups, name of Group sticker set.
+            Returned only in :meth:`telegram.Bot.get_chat`.
         can_set_sticker_set (:obj:`bool`): Optional. :obj:`True`, if the bot can change group the
-            sticker set.
+            sticker set. Returned only in :meth:`telegram.Bot.get_chat`.
         linked_chat_id (:obj:`int`): Optional. Unique identifier for the linked chat, i.e. the
             discussion group identifier for a channel and vice versa; for supergroups and channel
             chats. Returned only in :meth:`telegram.Bot.get_chat`.
@@ -199,7 +229,23 @@ class Chat(TelegramObject):
             in the private chat. Returned only in :meth:`telegram.Bot.get_chat`.
 
             .. versionadded:: 20.0
+        is_forum (:obj:`bool`): Optional. :obj:`True`, if the supergroup chat is a forum
+            (has topics_ enabled).
 
+            .. versionadded:: 20.0
+        active_usernames (List[:obj:`str`]): Optional. If set, the list of all `active chat
+            usernames <https://telegram.org/blog/topics-in-groups-collectible-usernames\
+            #collectible-usernames>`_; for private chats, supergroups and channels. Returned
+            only in :meth:`telegram.Bot.get_chat`.
+
+            .. versionadded:: 20.0
+        emoji_status_custom_emoji_id (:obj:`str`): Optional. Custom emoji identifier of emoji
+            status of the other party in a private chat. Returned only in
+            :meth:`telegram.Bot.get_chat`.
+
+            .. versionadded:: 20.0
+
+    .. _topics: https://telegram.org/blog/topics-in-groups-collectible-usernames#topics-in-groups
     """
 
     __slots__ = (
@@ -220,13 +266,15 @@ class Chat(TelegramObject):
         "title",
         "photo",
         "linked_chat_id",
-        "all_members_are_administrators",
         "message_auto_delete_time",
         "has_protected_content",
         "has_private_forwards",
         "join_to_send_messages",
         "join_by_request",
         "has_restricted_voice_and_video_messages",
+        "is_forum",
+        "active_usernames",
+        "emoji_status_custom_emoji_id",
     )
 
     SENDER: ClassVar[str] = constants.ChatType.SENDER
@@ -245,13 +293,12 @@ class Chat(TelegramObject):
 
     def __init__(
         self,
-        id: int,  # pylint: disable=invalid-name
+        id: int,
         type: str,
         title: str = None,
         username: str = None,
         first_name: str = None,
         last_name: str = None,
-        bot: "Bot" = None,
         photo: ChatPhoto = None,
         description: str = None,
         invite_link: str = None,
@@ -269,8 +316,13 @@ class Chat(TelegramObject):
         join_to_send_messages: bool = None,
         join_by_request: bool = None,
         has_restricted_voice_and_video_messages: bool = None,
-        **_kwargs: Any,
+        is_forum: bool = None,
+        active_usernames: List[str] = None,
+        emoji_status_custom_emoji_id: str = None,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
         # Required
         self.id = id  # pylint: disable=invalid-name
         self.type = enum.get_member(constants.ChatType, type, type)
@@ -279,8 +331,6 @@ class Chat(TelegramObject):
         self.username = username
         self.first_name = first_name
         self.last_name = last_name
-        # TODO: Remove (also from tests), when Telegram drops this completely
-        self.all_members_are_administrators = _kwargs.get("all_members_are_administrators")
         self.photo = photo
         self.bio = bio
         self.has_private_forwards = has_private_forwards
@@ -300,8 +350,10 @@ class Chat(TelegramObject):
         self.join_to_send_messages = join_to_send_messages
         self.join_by_request = join_by_request
         self.has_restricted_voice_and_video_messages = has_restricted_voice_and_video_messages
+        self.is_forum = is_forum
+        self.active_usernames = active_usernames
+        self.emoji_status_custom_emoji_id = emoji_status_custom_emoji_id
 
-        self.set_bot(bot)
         self._id_attrs = (self.id,)
 
     @property
@@ -346,7 +398,116 @@ class Chat(TelegramObject):
         data["permissions"] = ChatPermissions.de_json(data.get("permissions"), bot)
         data["location"] = ChatLocation.de_json(data.get("location"), bot)
 
-        return cls(bot=bot, **data)
+        api_kwargs = {}
+        # This is a deprecated field that TG still returns for backwards compatibility
+        # Let's filter it out to speed up the de-json process
+        if "all_members_are_administrators" in data:
+            api_kwargs["all_members_are_administrators"] = data.pop(
+                "all_members_are_administrators"
+            )
+
+        return super()._de_json(data=data, bot=bot, api_kwargs=api_kwargs)
+
+    def mention_markdown(self, name: str = None) -> str:
+        """
+        Note:
+            :tg-const:`telegram.constants.ParseMode.MARKDOWN` is a legacy mode, retained by
+            Telegram for backward compatibility. You should use :meth:`mention_markdown_v2`
+            instead.
+
+        .. versionadded:: 20.0
+
+        Args:
+            name (:obj:`str`): The name used as a link for the chat. Defaults to :attr:`full_name`.
+
+        Returns:
+            :obj:`str`: The inline mention for the chat as markdown (version 1).
+
+        Raises:
+            :exc:`TypeError`: If the chat is a private chat and neither the :paramref:`name`
+                nor the :attr:`first_name` is set, then throw an :exc:`TypeError`.
+                If the chat is a public chat and neither the :paramref:`name` nor the :attr:`title`
+                is set, then throw an :exc:`TypeError`. If chat is a private group chat, then
+                throw an :exc:`TypeError`.
+
+        """
+        if self.type == self.PRIVATE:
+            if name:
+                return helpers_mention_markdown(self.id, name)
+            if self.full_name:
+                return helpers_mention_markdown(self.id, self.full_name)
+            raise TypeError("Can not create a mention to a private chat without first name")
+        if self.username:
+            if name:
+                return f"[{name}]({self.link})"
+            if self.title:
+                return f"[{self.title}]({self.link})"
+            raise TypeError("Can not create a mention to a public chat without title")
+        raise TypeError("Can not create a mention to a private group chat")
+
+    def mention_markdown_v2(self, name: str = None) -> str:
+        """
+        .. versionadded:: 20.0
+
+        Args:
+            name (:obj:`str`): The name used as a link for the chat. Defaults to :attr:`full_name`.
+
+        Returns:
+            :obj:`str`: The inline mention for the chat as markdown (version 2).
+
+        Raises:
+            :exc:`TypeError`: If the chat is a private chat and neither the :paramref:`name`
+                nor the :attr:`first_name` is set, then throw an :exc:`TypeError`.
+                If the chat is a public chat and neither the :paramref:`name` nor the :attr:`title`
+                is set, then throw an :exc:`TypeError`. If chat is a private group chat, then
+                throw an :exc:`TypeError`.
+
+        """
+        if self.type == self.PRIVATE:
+            if name:
+                return helpers_mention_markdown(self.id, name, version=2)
+            if self.full_name:
+                return helpers_mention_markdown(self.id, self.full_name, version=2)
+            raise TypeError("Can not create a mention to a private chat without first name")
+        if self.username:
+            if name:
+                return f"[{escape_markdown(name, version=2)}]({self.link})"
+            if self.title:
+                return f"[{escape_markdown(self.title, version=2)}]({self.link})"
+            raise TypeError("Can not create a mention to a public chat without title")
+        raise TypeError("Can not create a mention to a private group chat")
+
+    def mention_html(self, name: str = None) -> str:
+        """
+        .. versionadded:: 20.0
+
+        Args:
+            name (:obj:`str`): The name used as a link for the chat. Defaults to :attr:`full_name`.
+
+        Returns:
+            :obj:`str`: The inline mention for the chat as HTML.
+
+        Raises:
+            :exc:`TypeError`: If the chat is a private chat and neither the :paramref:`name`
+                nor the :attr:`first_name` is set, then throw an :exc:`TypeError`.
+                If the chat is a public chat and neither the :paramref:`name` nor the :attr:`title`
+                is set, then throw an :exc:`TypeError`. If chat is a private group chat, then
+                throw an :exc:`TypeError`.
+
+        """
+        if self.type == self.PRIVATE:
+            if name:
+                return helpers_mention_html(self.id, name)
+            if self.full_name:
+                return helpers_mention_html(self.id, self.full_name)
+            raise TypeError("Can not create a mention to a private chat without first name")
+        if self.username:
+            if name:
+                return f'<a href="{self.link}">{escape(name)}</a>'
+            if self.title:
+                return f'<a href="{self.link}">{escape(self.title)}</a>'
+            raise TypeError("Can not create a mention to a public chat without title")
+        raise TypeError("Can not create a mention to a private group chat")
 
     async def leave(
         self,
@@ -682,6 +843,7 @@ class Chat(TelegramObject):
         is_anonymous: bool = None,
         can_manage_chat: bool = None,
         can_manage_video_chats: bool = None,
+        can_manage_topics: bool = None,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -725,6 +887,7 @@ class Chat(TelegramObject):
             is_anonymous=is_anonymous,
             can_manage_chat=can_manage_chat,
             can_manage_video_chats=can_manage_video_chats,
+            can_manage_topics=can_manage_topics,
         )
 
     async def restrict_member(
@@ -1072,6 +1235,7 @@ class Chat(TelegramObject):
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
         entities: Union[List["MessageEntity"], Tuple["MessageEntity", ...]] = None,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -1100,6 +1264,7 @@ class Chat(TelegramObject):
             allow_sending_without_reply=allow_sending_without_reply,
             entities=entities,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
             read_timeout=read_timeout,
             write_timeout=write_timeout,
             connect_timeout=connect_timeout,
@@ -1116,12 +1281,16 @@ class Chat(TelegramObject):
         reply_to_message_id: int = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = 20,
         connect_timeout: ODVInput[float] = DEFAULT_NONE,
         pool_timeout: ODVInput[float] = DEFAULT_NONE,
         api_kwargs: JSONDict = None,
+        caption: Optional[str] = None,
+        parse_mode: ODVInput[str] = DEFAULT_NONE,
+        caption_entities: Union[List["MessageEntity"], Tuple["MessageEntity", ...]] = None,
     ) -> List["Message"]:
         """Shortcut for::
 
@@ -1145,6 +1314,10 @@ class Chat(TelegramObject):
             api_kwargs=api_kwargs,
             allow_sending_without_reply=allow_sending_without_reply,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
+            caption=caption,
+            parse_mode=parse_mode,
+            caption_entities=caption_entities,
         )
 
     async def send_chat_action(
@@ -1191,6 +1364,7 @@ class Chat(TelegramObject):
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
         caption_entities: Union[List["MessageEntity"], Tuple["MessageEntity", ...]] = None,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         filename: str = None,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -1221,6 +1395,7 @@ class Chat(TelegramObject):
             caption_entities=caption_entities,
             filename=filename,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
             read_timeout=read_timeout,
             write_timeout=write_timeout,
             connect_timeout=connect_timeout,
@@ -1239,6 +1414,7 @@ class Chat(TelegramObject):
         vcard: str = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         contact: "Contact" = None,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -1274,6 +1450,7 @@ class Chat(TelegramObject):
             api_kwargs=api_kwargs,
             allow_sending_without_reply=allow_sending_without_reply,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
         )
 
     async def send_audio(
@@ -1291,6 +1468,7 @@ class Chat(TelegramObject):
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
         caption_entities: Union[List["MessageEntity"], Tuple["MessageEntity", ...]] = None,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         filename: str = None,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -1325,6 +1503,7 @@ class Chat(TelegramObject):
             caption_entities=caption_entities,
             filename=filename,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
             read_timeout=read_timeout,
             write_timeout=write_timeout,
             connect_timeout=connect_timeout,
@@ -1345,6 +1524,7 @@ class Chat(TelegramObject):
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
         caption_entities: Union[List["MessageEntity"], Tuple["MessageEntity", ...]] = None,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         filename: str = None,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -1382,6 +1562,7 @@ class Chat(TelegramObject):
             allow_sending_without_reply=allow_sending_without_reply,
             caption_entities=caption_entities,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
         )
 
     async def send_dice(
@@ -1392,6 +1573,7 @@ class Chat(TelegramObject):
         emoji: str = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -1422,6 +1604,7 @@ class Chat(TelegramObject):
             api_kwargs=api_kwargs,
             allow_sending_without_reply=allow_sending_without_reply,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
         )
 
     async def send_game(
@@ -1432,6 +1615,7 @@ class Chat(TelegramObject):
         reply_markup: "InlineKeyboardMarkup" = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -1462,6 +1646,7 @@ class Chat(TelegramObject):
             api_kwargs=api_kwargs,
             allow_sending_without_reply=allow_sending_without_reply,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
         )
 
     async def send_invoice(
@@ -1492,6 +1677,7 @@ class Chat(TelegramObject):
         max_tip_amount: int = None,
         suggested_tip_amounts: List[int] = None,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -1552,6 +1738,7 @@ class Chat(TelegramObject):
             max_tip_amount=max_tip_amount,
             suggested_tip_amounts=suggested_tip_amounts,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
         )
 
     async def send_location(
@@ -1567,6 +1754,7 @@ class Chat(TelegramObject):
         proximity_alert_radius: int = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         location: "Location" = None,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -1604,6 +1792,7 @@ class Chat(TelegramObject):
             proximity_alert_radius=proximity_alert_radius,
             allow_sending_without_reply=allow_sending_without_reply,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
         )
 
     async def send_animation(
@@ -1621,6 +1810,7 @@ class Chat(TelegramObject):
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
         caption_entities: Union[List["MessageEntity"], Tuple["MessageEntity", ...]] = None,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         filename: str = None,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -1660,6 +1850,7 @@ class Chat(TelegramObject):
             caption_entities=caption_entities,
             filename=filename,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
         )
 
     async def send_sticker(
@@ -1670,6 +1861,7 @@ class Chat(TelegramObject):
         reply_markup: ReplyMarkup = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = 20,
@@ -1700,6 +1892,7 @@ class Chat(TelegramObject):
             api_kwargs=api_kwargs,
             allow_sending_without_reply=allow_sending_without_reply,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
         )
 
     async def send_venue(
@@ -1717,6 +1910,7 @@ class Chat(TelegramObject):
         google_place_type: str = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         venue: "Venue" = None,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -1756,6 +1950,7 @@ class Chat(TelegramObject):
             google_place_type=google_place_type,
             allow_sending_without_reply=allow_sending_without_reply,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
         )
 
     async def send_video(
@@ -1774,6 +1969,7 @@ class Chat(TelegramObject):
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
         caption_entities: Union[List["MessageEntity"], Tuple["MessageEntity", ...]] = None,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         filename: str = None,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -1814,6 +2010,7 @@ class Chat(TelegramObject):
             caption_entities=caption_entities,
             filename=filename,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
         )
 
     async def send_video_note(
@@ -1827,6 +2024,7 @@ class Chat(TelegramObject):
         thumb: FileInput = None,
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         filename: str = None,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -1862,6 +2060,7 @@ class Chat(TelegramObject):
             allow_sending_without_reply=allow_sending_without_reply,
             filename=filename,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
         )
 
     async def send_voice(
@@ -1876,6 +2075,7 @@ class Chat(TelegramObject):
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
         caption_entities: Union[List["MessageEntity"], Tuple["MessageEntity", ...]] = None,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         filename: str = None,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -1912,6 +2112,7 @@ class Chat(TelegramObject):
             caption_entities=caption_entities,
             filename=filename,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
         )
 
     async def send_poll(
@@ -1933,6 +2134,7 @@ class Chat(TelegramObject):
         allow_sending_without_reply: ODVInput[bool] = DEFAULT_NONE,
         explanation_entities: Union[List["MessageEntity"], Tuple["MessageEntity", ...]] = None,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -1974,6 +2176,7 @@ class Chat(TelegramObject):
             allow_sending_without_reply=allow_sending_without_reply,
             explanation_entities=explanation_entities,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
         )
 
     async def send_copy(
@@ -1988,6 +2191,7 @@ class Chat(TelegramObject):
         allow_sending_without_reply: DVInput[bool] = DEFAULT_NONE,
         reply_markup: ReplyMarkup = None,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -2022,6 +2226,7 @@ class Chat(TelegramObject):
             pool_timeout=pool_timeout,
             api_kwargs=api_kwargs,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
         )
 
     async def copy_message(
@@ -2036,6 +2241,7 @@ class Chat(TelegramObject):
         allow_sending_without_reply: DVInput[bool] = DEFAULT_NONE,
         reply_markup: ReplyMarkup = None,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -2070,6 +2276,7 @@ class Chat(TelegramObject):
             pool_timeout=pool_timeout,
             api_kwargs=api_kwargs,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
         )
 
     async def forward_from(
@@ -2078,6 +2285,7 @@ class Chat(TelegramObject):
         message_id: int,
         disable_notification: DVInput[bool] = DEFAULT_NONE,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -2110,6 +2318,7 @@ class Chat(TelegramObject):
             pool_timeout=pool_timeout,
             api_kwargs=api_kwargs,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
         )
 
     async def forward_to(
@@ -2118,6 +2327,7 @@ class Chat(TelegramObject):
         message_id: int,
         disable_notification: DVInput[bool] = DEFAULT_NONE,
         protect_content: ODVInput[bool] = DEFAULT_NONE,
+        message_thread_id: int = None,
         *,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = DEFAULT_NONE,
@@ -2150,6 +2360,7 @@ class Chat(TelegramObject):
             pool_timeout=pool_timeout,
             api_kwargs=api_kwargs,
             protect_content=protect_content,
+            message_thread_id=message_thread_id,
         )
 
     async def export_invite_link(
@@ -2406,6 +2617,207 @@ class Chat(TelegramObject):
             api_kwargs=api_kwargs,
         )
 
+    async def create_forum_topic(
+        self,
+        name: str,
+        icon_color: int = None,
+        icon_custom_emoji_id: str = None,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: JSONDict = None,
+    ) -> bool:
+        """Shortcut for::
+
+             await bot.create_forum_topic(chat_id=update.effective_chat.id, *args, **kwargs)
+
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.create_forum_topic`.
+
+        .. versionadded:: 20.0
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+        """
+        return await self.get_bot().create_forum_topic(
+            chat_id=self.id,
+            name=name,
+            icon_color=icon_color,
+            icon_custom_emoji_id=icon_custom_emoji_id,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    async def edit_forum_topic(
+        self,
+        message_thread_id: int,
+        name: str,
+        icon_custom_emoji_id: str,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: JSONDict = None,
+    ) -> bool:
+        """Shortcut for::
+
+             await bot.edit_forum_topic(chat_id=update.effective_chat.id, *args, **kwargs)
+
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.edit_forum_topic`.
+
+        .. versionadded:: 20.0
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+        """
+        return await self.get_bot().edit_forum_topic(
+            chat_id=self.id,
+            message_thread_id=message_thread_id,
+            name=name,
+            icon_custom_emoji_id=icon_custom_emoji_id,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    async def close_forum_topic(
+        self,
+        message_thread_id: int,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: JSONDict = None,
+    ) -> bool:
+        """Shortcut for::
+
+             await bot.close_forum_topic(chat_id=update.effective_chat.id, *args, **kwargs)
+
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.close_forum_topic`.
+
+        .. versionadded:: 20.0
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+        """
+        return await self.get_bot().close_forum_topic(
+            chat_id=self.id,
+            message_thread_id=message_thread_id,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    async def reopen_forum_topic(
+        self,
+        message_thread_id: int,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: JSONDict = None,
+    ) -> bool:
+        """Shortcut for::
+
+             await bot.reopen_forum_topic(chat_id=update.effective_chat.id, *args, **kwargs)
+
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.reopen_forum_topic`.
+
+        .. versionadded:: 20.0
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+        """
+        return await self.get_bot().reopen_forum_topic(
+            chat_id=self.id,
+            message_thread_id=message_thread_id,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    async def delete_forum_topic(
+        self,
+        message_thread_id: int,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: JSONDict = None,
+    ) -> bool:
+        """Shortcut for::
+
+             await bot.delete_forum_topic(chat_id=update.effective_chat.id, *args, **kwargs)
+
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.delete_forum_topic`.
+
+        .. versionadded:: 20.0
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+        """
+        return await self.get_bot().delete_forum_topic(
+            chat_id=self.id,
+            message_thread_id=message_thread_id,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    async def unpin_all_forum_topic_messages(
+        self,
+        message_thread_id: int,
+        *,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+        api_kwargs: JSONDict = None,
+    ) -> bool:
+        """Shortcut for::
+
+             await bot.unpin_all_forum_topic_messages(chat_id=update.effective_chat.id,
+                *args, **kwargs)
+
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.unpin_all_forum_topic_messages`.
+
+        .. versionadded:: 20.0
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+        """
+        return await self.get_bot().unpin_all_forum_topic_messages(
+            chat_id=self.id,
+            message_thread_id=message_thread_id,
+            read_timeout=read_timeout,
+            write_timeout=write_timeout,
+            connect_timeout=connect_timeout,
+            pool_timeout=pool_timeout,
+            api_kwargs=api_kwargs,
+        )
+
     async def get_menu_button(
         self,
         *,

telegram/_chatadministratorrights.py

@@ -18,9 +18,8 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the class which represents a Telegram ChatAdministratorRights."""
 
-from typing import Any
-
 from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
 
 
 class ChatAdministratorRights(TelegramObject):
@@ -30,7 +29,12 @@ class ChatAdministratorRights(TelegramObject):
     considered equal, if their :attr:`is_anonymous`, :attr:`can_manage_chat`,
     :attr:`can_delete_messages`, :attr:`can_manage_video_chats`, :attr:`can_restrict_members`,
     :attr:`can_promote_members`, :attr:`can_change_info`, :attr:`can_invite_users`,
-    :attr:`can_post_messages`, :attr:`can_edit_messages`, :attr:`can_pin_messages` are equal.
+    :attr:`can_post_messages`, :attr:`can_edit_messages`, :attr:`can_pin_messages`,
+    :attr:`can_manage_topics` are equal.
+
+    .. versionchanged:: 20.0
+        :attr:`can_manage_topics` is considered as well when comparing objects of
+        this type in terms of equality.
 
     .. seealso: :meth:`Bot.set_my_default_administrator_rights`,
         :meth:`Bot.get_my_default_administrator_rights`
@@ -63,6 +67,10 @@ class ChatAdministratorRights(TelegramObject):
             messages of other users.
         can_pin_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed to pin
             messages; groups and supergroups only.
+        can_manage_topics (:obj:`bool`, optional): :obj:`True`, if the user is allowed
+            to create, rename, close, and reopen forum topics; supergroups only.
+
+            .. versionadded:: 20.0
 
     Attributes:
         is_anonymous (:obj:`bool`): :obj:`True`, if the user's presence in the chat is hidden.
@@ -90,6 +98,10 @@ class ChatAdministratorRights(TelegramObject):
             messages of other users.
         can_pin_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to pin
             messages; groups and supergroups only.
+        can_manage_topics (:obj:`bool`): Optional. :obj:`True`, if the user is allowed
+            to create, rename, close, and reopen forum topics; supergroups only.
+
+            .. versionadded:: 20.0
     """
 
     __slots__ = (
@@ -104,6 +116,7 @@ class ChatAdministratorRights(TelegramObject):
         "can_post_messages",
         "can_edit_messages",
         "can_pin_messages",
+        "can_manage_topics",
     )
 
     def __init__(
@@ -119,8 +132,11 @@ class ChatAdministratorRights(TelegramObject):
         can_post_messages: bool = None,
         can_edit_messages: bool = None,
         can_pin_messages: bool = None,
-        **_kwargs: Any,
+        can_manage_topics: bool = None,
+        *,
+        api_kwargs: JSONDict = None,
     ) -> None:
+        super().__init__(api_kwargs=api_kwargs)
         # Required
         self.is_anonymous = is_anonymous
         self.can_manage_chat = can_manage_chat
@@ -134,6 +150,7 @@ class ChatAdministratorRights(TelegramObject):
         self.can_post_messages = can_post_messages
         self.can_edit_messages = can_edit_messages
         self.can_pin_messages = can_pin_messages
+        self.can_manage_topics = can_manage_topics
 
         self._id_attrs = (
             self.is_anonymous,
@@ -147,6 +164,7 @@ class ChatAdministratorRights(TelegramObject):
             self.can_post_messages,
             self.can_edit_messages,
             self.can_pin_messages,
+            self.can_manage_topics,
         )
 
     @classmethod
@@ -158,7 +176,7 @@ class ChatAdministratorRights(TelegramObject):
 
         .. versionadded:: 20.0
         """
-        return cls(True, True, True, True, True, True, True, True, True, True, True)
+        return cls(True, True, True, True, True, True, True, True, True, True, True, True)
 
     @classmethod
     def no_rights(cls) -> "ChatAdministratorRights":
@@ -168,4 +186,6 @@ class ChatAdministratorRights(TelegramObject):
 
         .. versionadded:: 20.0
         """
-        return cls(False, False, False, False, False, False, False, False, False, False, False)
+        return cls(
+            False, False, False, False, False, False, False, False, False, False, False, False
+        )

telegram/_chatinvitelink.py

@@ -18,11 +18,11 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents an invite link for a chat."""
 import datetime
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Optional
 
 from telegram._telegramobject import TelegramObject
 from telegram._user import User
-from telegram._utils.datetime import from_timestamp, to_timestamp
+from telegram._utils.datetime import from_timestamp
 from telegram._utils.types import JSONDict
 
 if TYPE_CHECKING:
@@ -56,7 +56,8 @@ class ChatInviteLink(TelegramObject):
             has been expired.
         member_limit (:obj:`int`, optional): Maximum number of users that can be members of the
             chat simultaneously after joining the chat via this invite link;
-            1-:tg-const:`telegram.constants.ChatInviteLinkLimit.MEMBER_LIMIT`.
+            :tg-const:`telegram.constants.ChatInviteLinkLimit.MIN_MEMBER_LIMIT`-
+            :tg-const:`telegram.constants.ChatInviteLinkLimit.MAX_MEMBER_LIMIT`.
         name (:obj:`str`, optional): Invite link name.
             0-:tg-const:`telegram.constants.ChatInviteLinkLimit.NAME_LENGTH` characters.
 
@@ -65,7 +66,6 @@ class ChatInviteLink(TelegramObject):
             created using this link.
 
             .. versionadded:: 13.8
-
     Attributes:
         invite_link (:obj:`str`): The invite link. If the link was created by another chat
             administrator, then the second part of the link will be replaced with ``'…'``.
@@ -79,7 +79,9 @@ class ChatInviteLink(TelegramObject):
         expire_date (:class:`datetime.datetime`): Optional. Date when the link will expire or
             has been expired.
         member_limit (:obj:`int`): Optional. Maximum number of users that can be members
-            of the chat simultaneously after joining the chat via this invite link; 1-99999.
+            of the chat simultaneously after joining the chat via this invite link;
+            :tg-const:`telegram.constants.ChatInviteLinkLimit.MIN_MEMBER_LIMIT`-
+            :tg-const:`telegram.constants.ChatInviteLinkLimit.MAX_MEMBER_LIMIT`.
         name (:obj:`str`): Optional. Invite link name.
 
             .. versionadded:: 13.8
@@ -113,8 +115,10 @@ class ChatInviteLink(TelegramObject):
         member_limit: int = None,
         name: str = None,
         pending_join_request_count: int = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
         # Required
         self.invite_link = invite_link
         self.creator = creator
@@ -148,12 +152,4 @@ class ChatInviteLink(TelegramObject):
         data["creator"] = User.de_json(data.get("creator"), bot)
         data["expire_date"] = from_timestamp(data.get("expire_date", None))
 
-        return cls(**data)
-
-    def to_dict(self) -> JSONDict:
-        """See :meth:`telegram.TelegramObject.to_dict`."""
-        data = super().to_dict()
-
-        data["expire_date"] = to_timestamp(self.expire_date)
-
-        return data
+        return super().de_json(data=data, bot=bot)

telegram/_chatjoinrequest.py

@@ -18,13 +18,13 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram ChatJoinRequest."""
 import datetime
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Optional
 
 from telegram._chat import Chat
 from telegram._chatinvitelink import ChatInviteLink
 from telegram._telegramobject import TelegramObject
 from telegram._user import User
-from telegram._utils.datetime import from_timestamp, to_timestamp
+from telegram._utils.datetime import from_timestamp
 from telegram._utils.defaultvalue import DEFAULT_NONE
 from telegram._utils.types import JSONDict, ODVInput
 
@@ -53,7 +53,6 @@ class ChatJoinRequest(TelegramObject):
         bio (:obj:`str`, optional): Bio of the user.
         invite_link (:class:`telegram.ChatInviteLink`, optional): Chat invite link that was used
             by the user to send the join request.
-        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
 
     Attributes:
         chat (:class:`telegram.Chat`): Chat to which the request was sent.
@@ -74,9 +73,10 @@ class ChatJoinRequest(TelegramObject):
         date: datetime.datetime,
         bio: str = None,
         invite_link: ChatInviteLink = None,
-        bot: "Bot" = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
         # Required
         self.chat = chat
         self.from_user = from_user
@@ -86,7 +86,6 @@ class ChatJoinRequest(TelegramObject):
         self.bio = bio
         self.invite_link = invite_link
 
-        self.set_bot(bot)
         self._id_attrs = (self.chat, self.from_user, self.date)
 
     @classmethod
@@ -98,19 +97,11 @@ class ChatJoinRequest(TelegramObject):
             return None
 
         data["chat"] = Chat.de_json(data.get("chat"), bot)
-        data["from_user"] = User.de_json(data.get("from"), bot)
+        data["from_user"] = User.de_json(data.pop("from", None), bot)
         data["date"] = from_timestamp(data.get("date", None))
         data["invite_link"] = ChatInviteLink.de_json(data.get("invite_link"), bot)
 
-        return cls(bot=bot, **data)
-
-    def to_dict(self) -> JSONDict:
-        """See :meth:`telegram.TelegramObject.to_dict`."""
-        data = super().to_dict()
-
-        data["date"] = to_timestamp(self.date)
-
-        return data
+        return super().de_json(data=data, bot=bot)
 
     async def approve(
         self,

telegram/_chatlocation.py

@@ -18,8 +18,9 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a location to which a chat is connected."""
 
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, ClassVar, Optional
 
+from telegram import constants
 from telegram._files.location import Location
 from telegram._telegramobject import TelegramObject
 from telegram._utils.types import JSONDict
@@ -37,9 +38,9 @@ class ChatLocation(TelegramObject):
     Args:
         location (:class:`telegram.Location`): The location to which the supergroup is connected.
             Can't be a live location.
-        address (:obj:`str`): Location address; 1-64 characters, as defined by the chat owner
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
-
+        address (:obj:`str`): Location address;
+            :tg-const:`telegram.ChatLocation.MIN_ADDRESS`-
+            :tg-const:`telegram.ChatLocation.MAX_ADDRESS` characters, as defined by the chat owner
     Attributes:
         location (:class:`telegram.Location`): The location to which the supergroup is connected.
         address (:obj:`str`): Location address, as defined by the chat owner
@@ -52,8 +53,10 @@ class ChatLocation(TelegramObject):
         self,
         location: Location,
         address: str,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
         self.location = location
         self.address = address
 
@@ -69,4 +72,15 @@ class ChatLocation(TelegramObject):
 
         data["location"] = Location.de_json(data.get("location"), bot)
 
-        return cls(bot=bot, **data)
+        return super().de_json(data=data, bot=bot)
+
+    MIN_ADDRESS: ClassVar[int] = constants.LocationLimit.MIN_CHAT_LOCATION_ADDRESS
+    """:const:`telegram.constants.LocationLimit.MIN_CHAT_LOCATION_ADDRESS`
+
+    .. versionadded:: 20.0
+    """
+    MAX_ADDRESS: ClassVar[int] = constants.LocationLimit.MAX_CHAT_LOCATION_ADDRESS
+    """:const:`telegram.constants.LocationLimit.MAX_CHAT_LOCATION_ADDRESS`
+
+    .. versionadded:: 20.0
+    """

telegram/_chatmember.py

@@ -23,7 +23,7 @@ from typing import TYPE_CHECKING, ClassVar, Dict, Optional, Type
 from telegram import constants
 from telegram._telegramobject import TelegramObject
 from telegram._user import User
-from telegram._utils.datetime import from_timestamp, to_timestamp
+from telegram._utils.datetime import from_timestamp
 from telegram._utils.types import JSONDict
 
 if TYPE_CHECKING:
@@ -44,7 +44,8 @@ class ChatMember(TelegramObject):
     Objects of this class are comparable in terms of equality. Two objects of this class are
     considered equal, if their :attr:`user` and :attr:`status` are equal.
 
-    .. seealso:: `Chat Member Example <examples.chatmemberbot.html>`_
+    Examples:
+         :any:`Chat Member Bot <examples.chatmemberbot>`
 
     .. versionchanged:: 20.0
 
@@ -83,7 +84,14 @@ class ChatMember(TelegramObject):
     RESTRICTED: ClassVar[str] = constants.ChatMemberStatus.RESTRICTED
     """:const:`telegram.constants.ChatMemberStatus.RESTRICTED`"""
 
-    def __init__(self, user: User, status: str, **_kwargs: object):
+    def __init__(
+        self,
+        user: User,
+        status: str,
+        *,
+        api_kwargs: JSONDict = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
         # Required by all subclasses
         self.user = user
         self.status = status
@@ -98,9 +106,6 @@ class ChatMember(TelegramObject):
         if not data:
             return None
 
-        data["user"] = User.de_json(data.get("user"), bot)
-        data["until_date"] = from_timestamp(data.get("until_date", None))
-
         _class_mapping: Dict[str, Type["ChatMember"]] = {
             cls.OWNER: ChatMemberOwner,
             cls.ADMINISTRATOR: ChatMemberAdministrator,
@@ -110,18 +115,14 @@ class ChatMember(TelegramObject):
             cls.BANNED: ChatMemberBanned,
         }
 
-        if cls is ChatMember:
-            return _class_mapping.get(data["status"], cls)(**data, bot=bot)
-        return cls(**data)
+        if cls is ChatMember and data.get("status") in _class_mapping:
+            return _class_mapping[data.pop("status")].de_json(data=data, bot=bot)
 
-    def to_dict(self) -> JSONDict:
-        """See :meth:`telegram.TelegramObject.to_dict`."""
-        data = super().to_dict()
+        data["user"] = User.de_json(data.get("user"), bot)
+        if "until_date" in data:
+            data["until_date"] = from_timestamp(data["until_date"])
 
-        if data.get("until_date", False):
-            data["until_date"] = to_timestamp(data["until_date"])
-
-        return data
+        return super().de_json(data=data, bot=bot)
 
 
 class ChatMemberOwner(ChatMember):
@@ -154,9 +155,10 @@ class ChatMemberOwner(ChatMember):
         user: User,
         is_anonymous: bool,
         custom_title: str = None,
-        **_kwargs: object,
+        *,
+        api_kwargs: JSONDict = None,
     ):
-        super().__init__(status=ChatMember.OWNER, user=user)
+        super().__init__(status=ChatMember.OWNER, user=user, api_kwargs=api_kwargs)
         self.is_anonymous = is_anonymous
         self.custom_title = custom_title
 
@@ -167,9 +169,12 @@ class ChatMemberAdministrator(ChatMember):
 
     .. versionadded:: 13.7
     .. versionchanged:: 20.0
-       Argument and attribute ``can_manage_voice_chats`` were renamed to
-       :paramref:`can_manage_video_chats` and  :attr:`can_manage_video_chats` in accordance to
-       Bot API 6.0.
+
+       * Argument and attribute ``can_manage_voice_chats`` were renamed to
+         :paramref:`can_manage_video_chats` and  :attr:`can_manage_video_chats` in accordance to
+         Bot API 6.0.
+       * The argument :paramref:`can_manage_topics` was added, which changes the position of the
+         optional argument :paramref:`custom_title`.
 
     Args:
         user (:class:`telegram.User`): Information about the user.
@@ -204,6 +209,10 @@ class ChatMemberAdministrator(ChatMember):
             messages; channels only.
         can_pin_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed
             to pin messages; groups and supergroups only.
+        can_manage_topics (:obj:`bool`, optional): :obj:`True`, if the user is allowed
+            to create, rename, close, and reopen forum topics; supergroups only.
+
+            .. versionadded:: 20.0
         custom_title (:obj:`str`, optional): Custom title for this user.
 
     Attributes:
@@ -241,6 +250,10 @@ class ChatMemberAdministrator(ChatMember):
             messages; channels only.
         can_pin_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed
             to pin messages; groups and supergroups only.
+        can_manage_topics (:obj:`bool`): Optional. :obj:`True`, if the user is allowed
+            to create, rename, close, and reopen forum topics; supergroups only
+
+            .. versionadded:: 20.0
         custom_title (:obj:`str`): Optional. Custom title for this user.
     """
 
@@ -257,6 +270,7 @@ class ChatMemberAdministrator(ChatMember):
         "can_post_messages",
         "can_edit_messages",
         "can_pin_messages",
+        "can_manage_topics",
         "custom_title",
     )
 
@@ -275,10 +289,12 @@ class ChatMemberAdministrator(ChatMember):
         can_post_messages: bool = None,
         can_edit_messages: bool = None,
         can_pin_messages: bool = None,
+        can_manage_topics: bool = None,
         custom_title: str = None,
-        **_kwargs: object,
+        *,
+        api_kwargs: JSONDict = None,
     ):
-        super().__init__(status=ChatMember.ADMINISTRATOR, user=user)
+        super().__init__(status=ChatMember.ADMINISTRATOR, user=user, api_kwargs=api_kwargs)
         self.can_be_edited = can_be_edited
         self.is_anonymous = is_anonymous
         self.can_manage_chat = can_manage_chat
@@ -291,6 +307,7 @@ class ChatMemberAdministrator(ChatMember):
         self.can_post_messages = can_post_messages
         self.can_edit_messages = can_edit_messages
         self.can_pin_messages = can_pin_messages
+        self.can_manage_topics = can_manage_topics
         self.custom_title = custom_title
 
 
@@ -313,8 +330,13 @@ class ChatMemberMember(ChatMember):
 
     __slots__ = ()
 
-    def __init__(self, user: User, **_kwargs: object):
-        super().__init__(status=ChatMember.MEMBER, user=user)
+    def __init__(
+        self,
+        user: User,
+        *,
+        api_kwargs: JSONDict = None,
+    ):
+        super().__init__(status=ChatMember.MEMBER, user=user, api_kwargs=api_kwargs)
 
 
 class ChatMemberRestricted(ChatMember):
@@ -323,6 +345,9 @@ class ChatMemberRestricted(ChatMember):
     in the chat. Supergroups only.
 
     .. versionadded:: 13.7
+    .. versionchanged:: 20.0
+       The argument :paramref:`can_manage_topics` was added, which changes the position of the
+       optional argument :paramref:`until_date`.
 
     Args:
         user (:class:`telegram.User`): Information about the user.
@@ -344,6 +369,10 @@ class ChatMemberRestricted(ChatMember):
             to send animations, games, stickers and use inline bots.
         can_add_web_page_previews (:obj:`bool`): :obj:`True`, if the user is
            allowed to add web page previews to their messages.
+        can_manage_topics (:obj:`bool`): :obj:`True`, if the user is allowed to create
+            forum topics.
+
+            .. versionadded:: 20.0
         until_date (:class:`datetime.datetime`): Date when restrictions
            will be lifted for this user.
 
@@ -369,6 +398,10 @@ class ChatMemberRestricted(ChatMember):
             to send animations, games, stickers and use inline bots.
         can_add_web_page_previews (:obj:`bool`): :obj:`True`, if the user is
            allowed to add web page previews to their messages.
+        can_manage_topics (:obj:`bool`): :obj:`True`, if the user is allowed to create
+            forum topics.
+
+            .. versionadded:: 20.0
         until_date (:class:`datetime.datetime`): Date when restrictions
            will be lifted for this user.
 
@@ -384,6 +417,7 @@ class ChatMemberRestricted(ChatMember):
         "can_send_polls",
         "can_send_other_messages",
         "can_add_web_page_previews",
+        "can_manage_topics",
         "until_date",
     )
 
@@ -399,10 +433,12 @@ class ChatMemberRestricted(ChatMember):
         can_send_polls: bool,
         can_send_other_messages: bool,
         can_add_web_page_previews: bool,
+        can_manage_topics: bool,
         until_date: datetime.datetime,
-        **_kwargs: object,
+        *,
+        api_kwargs: JSONDict = None,
     ):
-        super().__init__(status=ChatMember.RESTRICTED, user=user)
+        super().__init__(status=ChatMember.RESTRICTED, user=user, api_kwargs=api_kwargs)
         self.is_member = is_member
         self.can_change_info = can_change_info
         self.can_invite_users = can_invite_users
@@ -412,6 +448,7 @@ class ChatMemberRestricted(ChatMember):
         self.can_send_polls = can_send_polls
         self.can_send_other_messages = can_send_other_messages
         self.can_add_web_page_previews = can_add_web_page_previews
+        self.can_manage_topics = can_manage_topics
         self.until_date = until_date
 
 
@@ -433,8 +470,13 @@ class ChatMemberLeft(ChatMember):
 
     __slots__ = ()
 
-    def __init__(self, user: User, **_kwargs: object):
-        super().__init__(status=ChatMember.LEFT, user=user)
+    def __init__(
+        self,
+        user: User,
+        *,
+        api_kwargs: JSONDict = None,
+    ):
+        super().__init__(status=ChatMember.LEFT, user=user, api_kwargs=api_kwargs)
 
 
 class ChatMemberBanned(ChatMember):
@@ -460,6 +502,12 @@ class ChatMemberBanned(ChatMember):
 
     __slots__ = ("until_date",)
 
-    def __init__(self, user: User, until_date: datetime.datetime, **_kwargs: object):
-        super().__init__(status=ChatMember.BANNED, user=user)
+    def __init__(
+        self,
+        user: User,
+        until_date: datetime.datetime,
+        *,
+        api_kwargs: JSONDict = None,
+    ):
+        super().__init__(status=ChatMember.BANNED, user=user, api_kwargs=api_kwargs)
         self.until_date = until_date

telegram/_chatmemberupdated.py

@@ -18,14 +18,14 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram ChatMemberUpdated."""
 import datetime
-from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple, Union
+from typing import TYPE_CHECKING, Dict, Optional, Tuple, Union
 
 from telegram._chat import Chat
 from telegram._chatinvitelink import ChatInviteLink
 from telegram._chatmember import ChatMember
 from telegram._telegramobject import TelegramObject
 from telegram._user import User
-from telegram._utils.datetime import from_timestamp, to_timestamp
+from telegram._utils.datetime import from_timestamp
 from telegram._utils.types import JSONDict
 
 if TYPE_CHECKING:
@@ -44,6 +44,9 @@ class ChatMemberUpdated(TelegramObject):
     Note:
         In Python :keyword:`from` is a reserved word use :paramref:`from_user` instead.
 
+    Examples:
+        :any:`Chat Member Bot <examples.chatmemberbot>`
+
     Args:
         chat (:class:`telegram.Chat`): Chat the user belongs to.
         from_user (:class:`telegram.User`): Performer of the action, which resulted in the change.
@@ -83,8 +86,10 @@ class ChatMemberUpdated(TelegramObject):
         old_chat_member: ChatMember,
         new_chat_member: ChatMember,
         invite_link: ChatInviteLink = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
         # Required
         self.chat = chat
         self.from_user = from_user
@@ -112,22 +117,13 @@ class ChatMemberUpdated(TelegramObject):
             return None
 
         data["chat"] = Chat.de_json(data.get("chat"), bot)
-        data["from_user"] = User.de_json(data.get("from"), bot)
+        data["from_user"] = User.de_json(data.pop("from", None), bot)
         data["date"] = from_timestamp(data.get("date"))
         data["old_chat_member"] = ChatMember.de_json(data.get("old_chat_member"), bot)
         data["new_chat_member"] = ChatMember.de_json(data.get("new_chat_member"), bot)
         data["invite_link"] = ChatInviteLink.de_json(data.get("invite_link"), bot)
 
-        return cls(**data)
-
-    def to_dict(self) -> JSONDict:
-        """See :meth:`telegram.TelegramObject.to_dict`."""
-        data = super().to_dict()
-
-        # Required
-        data["date"] = to_timestamp(self.date)
-
-        return data
+        return super().de_json(data=data, bot=bot)
 
     def _get_attribute_difference(self, attribute: str) -> Tuple[object, object]:
         try:

telegram/_chatpermissions.py

@@ -18,9 +18,8 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram ChatPermission."""
 
-from typing import Any
-
 from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
 
 
 class ChatPermissions(TelegramObject):
@@ -29,12 +28,17 @@ class ChatPermissions(TelegramObject):
     Objects of this class are comparable in terms of equality. Two objects of this class are
     considered equal, if their :attr:`can_send_messages`, :attr:`can_send_media_messages`,
     :attr:`can_send_polls`, :attr:`can_send_other_messages`, :attr:`can_add_web_page_previews`,
-    :attr:`can_change_info`, :attr:`can_invite_users` and :attr:`can_pin_messages` are equal.
+    :attr:`can_change_info`, :attr:`can_invite_users`, :attr:`can_pin_messages`, and
+    :attr:`can_manage_topics` are equal.
+
+    .. versionchanged:: 20.0
+        :attr:`can_manage_topics` is considered as well when comparing objects of
+        this type in terms of equality.
 
     Note:
         Though not stated explicitly in the official docs, Telegram changes not only the
         permissions that are set, but also sets all the others to :obj:`False`. However, since not
-        documented, this behaviour may change unbeknown to PTB.
+        documented, this behavior may change unbeknown to PTB.
 
     Args:
         can_send_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed to send text
@@ -55,6 +59,11 @@ class ChatPermissions(TelegramObject):
             users to the chat.
         can_pin_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed to pin
             messages. Ignored in public supergroups.
+        can_manage_topics (:obj:`bool`, optional): :obj:`True`, if the user is allowed
+            to create forum topics. If omitted defaults to the value of
+            :attr:`can_pin_messages`.
+
+            .. versionadded:: 20.0
 
     Attributes:
         can_send_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to send text
@@ -75,6 +84,11 @@ class ChatPermissions(TelegramObject):
             new users to the chat.
         can_pin_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to pin
             messages. Ignored in public supergroups.
+        can_manage_topics (:obj:`bool`): Optional. :obj:`True`, if the user is allowed
+            to create forum topics. If omitted defaults to the value of
+            :attr:`can_pin_messages`.
+
+            .. versionadded:: 20.0
 
     """
 
@@ -87,6 +101,7 @@ class ChatPermissions(TelegramObject):
         "can_change_info",
         "can_pin_messages",
         "can_add_web_page_previews",
+        "can_manage_topics",
     )
 
     def __init__(
@@ -99,8 +114,11 @@ class ChatPermissions(TelegramObject):
         can_change_info: bool = None,
         can_invite_users: bool = None,
         can_pin_messages: bool = None,
-        **_kwargs: Any,
+        can_manage_topics: bool = None,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
         # Required
         self.can_send_messages = can_send_messages
         self.can_send_media_messages = can_send_media_messages
@@ -110,6 +128,7 @@ class ChatPermissions(TelegramObject):
         self.can_change_info = can_change_info
         self.can_invite_users = can_invite_users
         self.can_pin_messages = can_pin_messages
+        self.can_manage_topics = can_manage_topics
 
         self._id_attrs = (
             self.can_send_messages,
@@ -120,6 +139,7 @@ class ChatPermissions(TelegramObject):
             self.can_change_info,
             self.can_invite_users,
             self.can_pin_messages,
+            self.can_manage_topics,
         )
 
     @classmethod
@@ -132,7 +152,7 @@ class ChatPermissions(TelegramObject):
         .. versionadded:: 20.0
 
         """
-        return cls(True, True, True, True, True, True, True, True)
+        return cls(True, True, True, True, True, True, True, True, True)
 
     @classmethod
     def no_permissions(cls) -> "ChatPermissions":
@@ -142,4 +162,4 @@ class ChatPermissions(TelegramObject):
 
         .. versionadded:: 20.0
         """
-        return cls(False, False, False, False, False, False, False, False)
+        return cls(False, False, False, False, False, False, False, False, False)

telegram/_choseninlineresult.py

@@ -19,7 +19,7 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram ChosenInlineResult."""
 
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Optional
 
 from telegram._files.location import Location
 from telegram._telegramobject import TelegramObject
@@ -52,7 +52,6 @@ class ChosenInlineResult(TelegramObject):
             only if there is an inline keyboard attached to the message. Will be also received in
             callback queries and can be used to edit the message.
         query (:obj:`str`): The query that was used to obtain the result.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         result_id (:obj:`str`): The unique identifier for the result that was chosen.
@@ -72,8 +71,11 @@ class ChosenInlineResult(TelegramObject):
         query: str,
         location: Location = None,
         inline_message_id: str = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
+
         # Required
         self.result_id = result_id
         self.from_user = from_user
@@ -93,8 +95,8 @@ class ChosenInlineResult(TelegramObject):
             return None
 
         # Required
-        data["from_user"] = User.de_json(data.pop("from"), bot)
+        data["from_user"] = User.de_json(data.pop("from", None), bot)
         # Optionals
         data["location"] = Location.de_json(data.get("location"), bot)
 
-        return cls(**data)
+        return super().de_json(data=data, bot=bot)

telegram/_dice.py

@@ -17,10 +17,11 @@
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram Dice."""
-from typing import Any, ClassVar, List
+from typing import ClassVar, List
 
 from telegram import constants
 from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
 
 
 class Dice(TelegramObject):
@@ -33,30 +34,43 @@ class Dice(TelegramObject):
     considered equal, if their :attr:`value` and :attr:`emoji` are equal.
 
     Note:
-        If :attr:`emoji` is "🎯", a value of 6 currently represents a bullseye, while a value of 1
-        indicates that the dartboard was missed. However, this behaviour is undocumented and might
-        be changed by Telegram.
+        If :attr:`emoji` is :tg-const:`telegram.Dice.DARTS`, a value of 6 currently
+        represents a bullseye, while a value of 1 indicates that the dartboard was missed.
+        However, this behaviour is undocumented and might be changed by Telegram.
 
-        If :attr:`emoji` is "🏀", a value of 4 or 5 currently score a basket, while a value of 1 to
-        3 indicates that the basket was missed. However, this behaviour is undocumented and might
-        be changed by Telegram.
+        If :attr:`emoji` is :tg-const:`telegram.Dice.BASKETBALL`, a value of 4 or 5
+        currently score a basket, while a value of 1 to 3 indicates that the basket was missed.
+        However, this behaviour is undocumented and might be changed by Telegram.
 
-        If :attr:`emoji` is "⚽", a value of 4 to 5 currently scores a goal, while a value of 1 to
-        3 indicates that the goal was missed. However, this behaviour is undocumented and might
-        be changed by Telegram.
+        If :attr:`emoji` is :tg-const:`telegram.Dice.FOOTBALL`, a value of 4 to 5
+        currently scores a goal, while a value of 1 to 3 indicates that the goal was missed.
+        However, this behaviour is undocumented and might be changed by Telegram.
 
-        If :attr:`emoji` is "🎳", a value of 6 knocks all the pins, while a value of 1 means all
-        the pins were missed. However, this behaviour is undocumented and might be changed by
-        Telegram.
+        If :attr:`emoji` is :tg-const:`telegram.Dice.BOWLING`, a value of 6 knocks
+        all the pins, while a value of 1 means all the pins were missed.
+        However, this behaviour is undocumented and might be changed by Telegram.
 
-        If :attr:`emoji` is "🎰", each value corresponds to a unique combination of symbols, which
+        If :attr:`emoji` is :tg-const:`telegram.Dice.SLOT_MACHINE`, each value
+        corresponds to a unique combination of symbols, which
         can be found at our `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki\
         /Code-snippets#map-a-slot-machine-dice-value-to-the-corresponding-symbols>`_.
         However, this behaviour is undocumented and might be changed by Telegram.
 
+    ..
+        In args, some links for limits of `value` intentionally point to constants for only
+        one emoji of a group to avoid duplication. For example, maximum value for Dice, Darts and
+        Bowling is linked to a constant for Bowling.
+
     Args:
-        value (:obj:`int`): Value of the dice. 1-6 for dice, darts and bowling balls, 1-5 for
-            basketball and football/soccer ball, 1-64 for slot machine.
+        value (:obj:`int`): Value of the dice.
+            :tg-const:`telegram.Dice.MIN_VALUE`-:tg-const:`telegram.Dice.MAX_VALUE_BOWLING`
+            for :tg-const:`telegram.Dice.DICE`, :tg-const:`telegram.Dice.DARTS` and
+            :tg-const:`telegram.Dice.BOWLING` base emoji,
+            :tg-const:`telegram.Dice.MIN_VALUE`-:tg-const:`telegram.Dice.MAX_VALUE_BASKETBALL`
+            for :tg-const:`telegram.Dice.BASKETBALL` and :tg-const:`telegram.Dice.FOOTBALL`
+            base emoji,
+            :tg-const:`telegram.Dice.MIN_VALUE`-:tg-const:`telegram.Dice.MAX_VALUE_SLOT_MACHINE`
+            for :tg-const:`telegram.Dice.SLOT_MACHINE` base emoji.
         emoji (:obj:`str`): Emoji on which the dice throw animation is based.
 
     Attributes:
@@ -67,7 +81,8 @@ class Dice(TelegramObject):
 
     __slots__ = ("emoji", "value")
 
-    def __init__(self, value: int, emoji: str, **_kwargs: Any):
+    def __init__(self, value: int, emoji: str, *, api_kwargs: JSONDict = None):
+        super().__init__(api_kwargs=api_kwargs)
         self.value = value
         self.emoji = emoji
 
@@ -91,3 +106,45 @@ class Dice(TelegramObject):
     """
     ALL_EMOJI: ClassVar[List[str]] = list(constants.DiceEmoji)
     """List[:obj:`str`]: A list of all available dice emoji."""
+
+    MIN_VALUE: ClassVar[int] = constants.DiceLimit.MIN_VALUE
+    """:const:`telegram.constants.DiceLimit.MIN_VALUE`
+
+    .. versionadded:: 20.0
+    """
+
+    MAX_VALUE_BOWLING: ClassVar[int] = constants.DiceLimit.MAX_VALUE_BOWLING
+    """:const:`telegram.constants.DiceLimit.MAX_VALUE_BOWLING`
+
+    .. versionadded:: 20.0
+    """
+
+    MAX_VALUE_DARTS: ClassVar[int] = constants.DiceLimit.MAX_VALUE_DARTS
+    """:const:`telegram.constants.DiceLimit.MAX_VALUE_DARTS`
+
+    .. versionadded:: 20.0
+    """
+
+    MAX_VALUE_DICE: ClassVar[int] = constants.DiceLimit.MAX_VALUE_DICE
+    """:const:`telegram.constants.DiceLimit.MAX_VALUE_DICE`
+
+    .. versionadded:: 20.0
+    """
+
+    MAX_VALUE_BASKETBALL: ClassVar[int] = constants.DiceLimit.MAX_VALUE_BASKETBALL
+    """:const:`telegram.constants.DiceLimit.MAX_VALUE_BASKETBALL`
+
+    .. versionadded:: 20.0
+    """
+
+    MAX_VALUE_FOOTBALL: ClassVar[int] = constants.DiceLimit.MAX_VALUE_FOOTBALL
+    """:const:`telegram.constants.DiceLimit.MAX_VALUE_FOOTBALL`
+
+    .. versionadded:: 20.0
+    """
+
+    MAX_VALUE_SLOT_MACHINE: ClassVar[int] = constants.DiceLimit.MAX_VALUE_SLOT_MACHINE
+    """:const:`telegram.constants.DiceLimit.MAX_VALUE_SLOT_MACHINE`
+
+    .. versionadded:: 20.0
+    """

telegram/_files/_basemedium.py

@@ -24,7 +24,7 @@ from telegram._utils.defaultvalue import DEFAULT_NONE
 from telegram._utils.types import JSONDict, ODVInput
 
 if TYPE_CHECKING:
-    from telegram import Bot, File
+    from telegram import File
 
 
 class _BaseMedium(TelegramObject):
@@ -39,7 +39,6 @@ class _BaseMedium(TelegramObject):
             is supposed to be the same over time and for different bots.
             Can't be used to download or reuse the file.
         file_size (:obj:`int`, optional): File size.
-        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
 
     Attributes:
         file_id (:obj:`str`): File identifier.
@@ -47,21 +46,27 @@ class _BaseMedium(TelegramObject):
             is supposed to be the same over time and for different bots.
             Can't be used to download or reuse the file.
         file_size (:obj:`int`): Optional. File size.
-        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
+
 
     """
 
     __slots__ = ("file_id", "file_size", "file_unique_id")
 
     def __init__(
-        self, file_id: str, file_unique_id: str, file_size: int = None, bot: "Bot" = None
+        self,
+        file_id: str,
+        file_unique_id: str,
+        file_size: int = None,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
+
         # Required
         self.file_id: str = str(file_id)
         self.file_unique_id = str(file_unique_id)
         # Optionals
         self.file_size = file_size
-        self.set_bot(bot)
 
         self._id_attrs = (self.file_unique_id,)
 

telegram/_files/_basethumbedmedium.py

@@ -45,7 +45,6 @@ class _BaseThumbedMedium(_BaseMedium):
             Can't be used to download or reuse the file.
         file_size (:obj:`int`, optional): File size.
         thumb (:class:`telegram.PhotoSize`, optional): Thumbnail as defined by sender.
-        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
 
     Attributes:
         file_id (:obj:`str`): File identifier.
@@ -54,7 +53,7 @@ class _BaseThumbedMedium(_BaseMedium):
             Can't be used to download or reuse the file.
         file_size (:obj:`int`): Optional. File size.
         thumb (:class:`telegram.PhotoSize`): Optional. Thumbnail as defined by sender.
-        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
+
 
     """
 
@@ -66,10 +65,14 @@ class _BaseThumbedMedium(_BaseMedium):
         file_unique_id: str,
         file_size: int = None,
         thumb: PhotoSize = None,
-        bot: "Bot" = None,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         super().__init__(
-            file_id=file_id, file_unique_id=file_unique_id, file_size=file_size, bot=bot
+            file_id=file_id,
+            file_unique_id=file_unique_id,
+            file_size=file_size,
+            api_kwargs=api_kwargs,
         )
         self.thumb = thumb
 
@@ -83,6 +86,8 @@ class _BaseThumbedMedium(_BaseMedium):
         if not data:
             return None
 
-        data["thumb"] = PhotoSize.de_json(data.get("thumb"), bot)
+        # In case this wasn't already done by the subclass
+        if not isinstance(data.get("thumb"), PhotoSize):
+            data["thumb"] = PhotoSize.de_json(data.get("thumb"), bot)
 
-        return cls(bot=bot, **data)
+        return super().de_json(data=data, bot=bot)

telegram/_files/animation.py

@@ -17,13 +17,10 @@
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram Animation."""
-from typing import TYPE_CHECKING, Any
 
 from telegram._files._basethumbedmedium import _BaseThumbedMedium
 from telegram._files.photosize import PhotoSize
-
-if TYPE_CHECKING:
-    from telegram import Bot
+from telegram._utils.types import JSONDict
 
 
 class Animation(_BaseThumbedMedium):
@@ -45,8 +42,6 @@ class Animation(_BaseThumbedMedium):
         file_name (:obj:`str`, optional): Original animation filename as defined by sender.
         mime_type (:obj:`str`, optional): MIME type of the file as defined by sender.
         file_size (:obj:`int`, optional): File size in bytes.
-        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         file_id (:obj:`str`): File identifier.
@@ -60,7 +55,7 @@ class Animation(_BaseThumbedMedium):
         file_name (:obj:`str`): Optional. Original animation filename as defined by sender.
         mime_type (:obj:`str`): Optional. MIME type of the file as defined by sender.
         file_size (:obj:`int`): Optional. File size in bytes.
-        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
+
 
     """
 
@@ -77,15 +72,15 @@ class Animation(_BaseThumbedMedium):
         file_name: str = None,
         mime_type: str = None,
         file_size: int = None,
-        bot: "Bot" = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         super().__init__(
             file_id=file_id,
             file_unique_id=file_unique_id,
             file_size=file_size,
             thumb=thumb,
-            bot=bot,
+            api_kwargs=api_kwargs,
         )
         # Required
         self.width = width

telegram/_files/audio.py

@@ -18,13 +18,9 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram Audio."""
 
-from typing import TYPE_CHECKING, Any
-
 from telegram._files._basethumbedmedium import _BaseThumbedMedium
 from telegram._files.photosize import PhotoSize
-
-if TYPE_CHECKING:
-    from telegram import Bot
+from telegram._utils.types import JSONDict
 
 
 class Audio(_BaseThumbedMedium):
@@ -33,6 +29,7 @@ class Audio(_BaseThumbedMedium):
     Objects of this class are comparable in terms of equality. Two objects of this class are
     considered equal, if their :attr:`file_unique_id` is equal.
 
+
     Args:
         file_id (:obj:`str`): Identifier for this file, which can be used to download
             or reuse the file.
@@ -47,8 +44,6 @@ class Audio(_BaseThumbedMedium):
         file_size (:obj:`int`, optional): File size in bytes.
         thumb (:class:`telegram.PhotoSize`, optional): Thumbnail of the album cover to
             which the music file belongs.
-        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         file_id (:obj:`str`): Identifier for this file.
@@ -64,7 +59,7 @@ class Audio(_BaseThumbedMedium):
         file_size (:obj:`int`): Optional. File size in bytes.
         thumb (:class:`telegram.PhotoSize`): Optional. Thumbnail of the album cover to
             which the music file belongs.
-        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
+
 
     """
 
@@ -80,16 +75,16 @@ class Audio(_BaseThumbedMedium):
         mime_type: str = None,
         file_size: int = None,
         thumb: PhotoSize = None,
-        bot: "Bot" = None,
         file_name: str = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         super().__init__(
             file_id=file_id,
             file_unique_id=file_unique_id,
             file_size=file_size,
             thumb=thumb,
-            bot=bot,
+            api_kwargs=api_kwargs,
         )
         # Required
         self.duration = duration

telegram/_files/chatphoto.py

@@ -17,14 +17,15 @@
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram ChatPhoto."""
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, ClassVar
 
+from telegram import constants
 from telegram._telegramobject import TelegramObject
 from telegram._utils.defaultvalue import DEFAULT_NONE
 from telegram._utils.types import JSONDict, ODVInput
 
 if TYPE_CHECKING:
-    from telegram import Bot, File
+    from telegram import File
 
 
 class ChatPhoto(TelegramObject):
@@ -35,32 +36,39 @@ class ChatPhoto(TelegramObject):
     equal.
 
     Args:
-        small_file_id (:obj:`str`): Unique file identifier of small (160x160) chat photo. This
-            file_id can be used only for photo download and only for as long
+        small_file_id (:obj:`str`): Unique file identifier of small
+            (:tg-const:`telegram.ChatPhoto.SIZE_SMALL` x :tg-const:`telegram.ChatPhoto.SIZE_SMALL`)
+            chat photo. This file_id can be used only for photo download and only for as long
             as the photo is not changed.
-        small_file_unique_id (:obj:`str`): Unique file identifier of small (160x160) chat photo,
-            which is supposed to be the same over time and for different bots.
+        small_file_unique_id (:obj:`str`): Unique file identifier of small
+            (:tg-const:`telegram.ChatPhoto.SIZE_SMALL` x :tg-const:`telegram.ChatPhoto.SIZE_SMALL`)
+            chat photo, which is supposed to be the same over time and for different bots.
             Can't be used to download or reuse the file.
-        big_file_id (:obj:`str`): Unique file identifier of big (640x640) chat photo. This file_id
-            can be used only for photo download and only for as long as the photo is not changed.
-        big_file_unique_id (:obj:`str`): Unique file identifier of big (640x640) chat photo,
-            which is supposed to be the same over time and for different bots.
+        big_file_id (:obj:`str`): Unique file identifier of big
+            (:tg-const:`telegram.ChatPhoto.SIZE_BIG` x :tg-const:`telegram.ChatPhoto.SIZE_BIG`)
+            chat photo. This file_id can be used only for photo download and only for as long as
+            the photo is not changed.
+        big_file_unique_id (:obj:`str`): Unique file identifier of big
+            (:tg-const:`telegram.ChatPhoto.SIZE_BIG` x :tg-const:`telegram.ChatPhoto.SIZE_BIG`)
+            chat photo, which is supposed to be the same over time and for different bots.
             Can't be used to download or reuse the file.
-        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
-        small_file_id (:obj:`str`): File identifier of small (160x160) chat photo.
-            This file_id can be used only for photo download and only for as long
+        small_file_id (:obj:`str`): File identifier of small
+            (:tg-const:`telegram.ChatPhoto.SIZE_SMALL` x :tg-const:`telegram.ChatPhoto.SIZE_SMALL`)
+            chat photo. This file_id can be used only for photo download and only for as long
             as the photo is not changed.
-        small_file_unique_id (:obj:`str`): Unique file identifier of small (160x160) chat photo,
-            which is supposed to be the same over time and for different bots.
+        small_file_unique_id (:obj:`str`): Unique file identifier of small
+            (:tg-const:`telegram.ChatPhoto.SIZE_SMALL` x :tg-const:`telegram.ChatPhoto.SIZE_SMALL`)
+            chat photo, which is supposed to be the same over time and for different bots.
             Can't be used to download or reuse the file.
-        big_file_id (:obj:`str`): File identifier of big (640x640) chat photo.
-            This file_id can be used only for photo download and only for as long as
+        big_file_id (:obj:`str`): File identifier of big
+            (:tg-const:`telegram.ChatPhoto.SIZE_BIG` x :tg-const:`telegram.ChatPhoto.SIZE_BIG`)
+            chat photo. This file_id can be used only for photo download and only for as long as
             the photo is not changed.
-        big_file_unique_id (:obj:`str`): Unique file identifier of big (640x640) chat photo,
-            which is supposed to be the same over time and for different bots.
+        big_file_unique_id (:obj:`str`): Unique file identifier of big
+            (:tg-const:`telegram.ChatPhoto.SIZE_BIG` x :tg-const:`telegram.ChatPhoto.SIZE_BIG`)
+            chat photo, which is supposed to be the same over time and for different bots.
             Can't be used to download or reuse the file.
 
     """
@@ -78,16 +86,15 @@ class ChatPhoto(TelegramObject):
         small_file_unique_id: str,
         big_file_id: str,
         big_file_unique_id: str,
-        bot: "Bot" = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
         self.small_file_id = small_file_id
         self.small_file_unique_id = small_file_unique_id
         self.big_file_id = big_file_id
         self.big_file_unique_id = big_file_unique_id
 
-        self.set_bot(bot)
-
         self._id_attrs = (
             self.small_file_unique_id,
             self.big_file_unique_id,
@@ -102,8 +109,9 @@ class ChatPhoto(TelegramObject):
         pool_timeout: ODVInput[float] = DEFAULT_NONE,
         api_kwargs: JSONDict = None,
     ) -> "File":
-        """Convenience wrapper over :attr:`telegram.Bot.get_file` for getting the
-        small (160x160) chat photo
+        """Convenience wrapper over :attr:`telegram.Bot.get_file` for getting the small
+        (:tg-const:`telegram.ChatPhoto.SIZE_SMALL` x :tg-const:`telegram.ChatPhoto.SIZE_SMALL`)
+        chat photo
 
         For the documentation of the arguments, please see :meth:`telegram.Bot.get_file`.
 
@@ -133,7 +141,8 @@ class ChatPhoto(TelegramObject):
         api_kwargs: JSONDict = None,
     ) -> "File":
         """Convenience wrapper over :attr:`telegram.Bot.get_file` for getting the
-        big (640x640) chat photo
+        big (:tg-const:`telegram.ChatPhoto.SIZE_BIG` x :tg-const:`telegram.ChatPhoto.SIZE_BIG`)
+        chat photo
 
         For the documentation of the arguments, please see :meth:`telegram.Bot.get_file`.
 
@@ -152,3 +161,14 @@ class ChatPhoto(TelegramObject):
             pool_timeout=pool_timeout,
             api_kwargs=api_kwargs,
         )
+
+    SIZE_SMALL: ClassVar[int] = constants.ChatPhotoSize.SMALL
+    """:const:`telegram.constants.ChatPhotoSize.SMALL`
+
+    .. versionadded:: 20.0
+    """
+    SIZE_BIG: ClassVar[int] = constants.ChatPhotoSize.BIG
+    """:const:`telegram.constants.ChatPhotoSize.BIG`
+
+    .. versionadded:: 20.0
+    """

telegram/_files/contact.py

@@ -18,9 +18,8 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram Contact."""
 
-from typing import Any
-
 from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
 
 
 class Contact(TelegramObject):
@@ -35,7 +34,6 @@ class Contact(TelegramObject):
         last_name (:obj:`str`, optional): Contact's last name.
         user_id (:obj:`int`, optional): Contact's user identifier in Telegram.
         vcard (:obj:`str`, optional): Additional data about the contact in the form of a vCard.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         phone_number (:obj:`str`): Contact's phone number.
@@ -55,8 +53,10 @@ class Contact(TelegramObject):
         last_name: str = None,
         user_id: int = None,
         vcard: str = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
         # Required
         self.phone_number = str(phone_number)
         self.first_name = first_name

telegram/_files/document.py

@@ -18,13 +18,9 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram Document."""
 
-from typing import TYPE_CHECKING, Any
-
 from telegram._files._basethumbedmedium import _BaseThumbedMedium
 from telegram._files.photosize import PhotoSize
-
-if TYPE_CHECKING:
-    from telegram import Bot
+from telegram._utils.types import JSONDict
 
 
 class Document(_BaseThumbedMedium):
@@ -43,8 +39,6 @@ class Document(_BaseThumbedMedium):
         file_name (:obj:`str`, optional): Original filename as defined by sender.
         mime_type (:obj:`str`, optional): MIME type of the file as defined by sender.
         file_size (:obj:`int`, optional): File size in bytes.
-        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         file_id (:obj:`str`): File identifier.
@@ -55,7 +49,7 @@ class Document(_BaseThumbedMedium):
         file_name (:obj:`str`): Original filename.
         mime_type (:obj:`str`): Optional. MIME type of the file.
         file_size (:obj:`int`): Optional. File size in bytes.
-        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
+
 
     """
 
@@ -69,15 +63,15 @@ class Document(_BaseThumbedMedium):
         file_name: str = None,
         mime_type: str = None,
         file_size: int = None,
-        bot: "Bot" = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         super().__init__(
             file_id=file_id,
             file_unique_id=file_unique_id,
             file_size=file_size,
             thumb=thumb,
-            bot=bot,
+            api_kwargs=api_kwargs,
         )
         # Optional
         self.mime_type = mime_type

telegram/_files/file.py

@@ -21,32 +21,36 @@ import shutil
 import urllib.parse as urllib_parse
 from base64 import b64decode
 from pathlib import Path
-from typing import IO, TYPE_CHECKING, Any, Optional, Union
+from typing import TYPE_CHECKING, BinaryIO, Optional
 
 from telegram._passport.credentials import decrypt
 from telegram._telegramobject import TelegramObject
 from telegram._utils.defaultvalue import DEFAULT_NONE
 from telegram._utils.files import is_local_file
-from telegram._utils.types import FilePathInput, ODVInput
+from telegram._utils.types import FilePathInput, JSONDict, ODVInput
 
 if TYPE_CHECKING:
-    from telegram import Bot, FileCredentials
+    from telegram import FileCredentials
 
 
 class File(TelegramObject):
     """
-    This object represents a file ready to be downloaded. The file can be downloaded with
-    :attr:`download`. It is guaranteed that the link will be valid for at least 1 hour. When the
-    link expires, a new one can be requested by calling :meth:`telegram.Bot.get_file`.
+    This object represents a file ready to be downloaded. The file can be e.g. downloaded with
+    :attr:`download_to_memory`. It is guaranteed that the link will be valid for at least 1 hour.
+    When the link expires, a new one can be requested by calling :meth:`telegram.Bot.get_file`.
 
     Objects of this class are comparable in terms of equality. Two objects of this class are
     considered equal, if their :attr:`file_unique_id` is equal.
 
+    .. versionchanged:: 20.0:
+        ``download`` was split into :meth:`download_to_memory` and :meth:`download_to_object`.
+
     Note:
         * Maximum file size to download is
           :tg-const:`telegram.constants.FileSizeLimit.FILESIZE_DOWNLOAD`.
         * If you obtain an instance of this class from :attr:`telegram.PassportFile.get_file`,
-          then it will automatically be decrypted as it downloads when you call :meth:`download()`.
+          then it will automatically be decrypted as it downloads when you call e.g.
+          :meth:`download_to_memory`.
 
     Args:
         file_id (:obj:`str`): Identifier for this file, which can be used to download
@@ -55,9 +59,8 @@ class File(TelegramObject):
             is supposed to be the same over time and for different bots.
             Can't be used to download or reuse the file.
         file_size (:obj:`int`, optional): Optional. File size in bytes, if known.
-        file_path (:obj:`str`, optional): File path. Use :attr:`download` to get the file.
-        bot (:obj:`telegram.Bot`, optional): Bot to use with shortcut method.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+        file_path (:obj:`str`, optional): File path. Use e.g. :meth:`download_to_memory` to get the
+            file.
 
     Attributes:
         file_id (:obj:`str`): Identifier for this file.
@@ -65,8 +68,8 @@ class File(TelegramObject):
             is supposed to be the same over time and for different bots.
             Can't be used to download or reuse the file.
         file_size (:obj:`str`): Optional. File size in bytes.
-        file_path (:obj:`str`): Optional. File path. Use :meth:`download` to get the file.
-
+        file_path (:obj:`str`): Optional. File path. Use e.g. :meth:`download_to_memory` to get
+            the file.
     """
 
     __slots__ = (
@@ -81,54 +84,73 @@ class File(TelegramObject):
         self,
         file_id: str,
         file_unique_id: str,
-        bot: "Bot" = None,
         file_size: int = None,
         file_path: str = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
+
         # Required
         self.file_id = str(file_id)
         self.file_unique_id = str(file_unique_id)
         # Optionals
         self.file_size = file_size
         self.file_path = file_path
-        self.set_bot(bot)
+
         self._credentials: Optional["FileCredentials"] = None
 
         self._id_attrs = (self.file_unique_id,)
 
-    async def download(
+    def _get_encoded_url(self) -> str:
+        """Convert any UTF-8 char in :obj:`File.file_path` into a url encoded ASCII string."""
+        sres = urllib_parse.urlsplit(str(self.file_path))
+        return urllib_parse.urlunsplit(
+            urllib_parse.SplitResult(
+                sres.scheme, sres.netloc, urllib_parse.quote(sres.path), sres.query, sres.fragment
+            )
+        )
+
+    def _prepare_decrypt(self, buf: bytes) -> bytes:
+        return decrypt(b64decode(self._credentials.secret), b64decode(self._credentials.hash), buf)
+
+    async def download_to_memory(
         self,
         custom_path: FilePathInput = None,
-        out: IO = None,
         read_timeout: ODVInput[float] = DEFAULT_NONE,
         write_timeout: ODVInput[float] = DEFAULT_NONE,
         connect_timeout: ODVInput[float] = DEFAULT_NONE,
         pool_timeout: ODVInput[float] = DEFAULT_NONE,
-    ) -> Union[Path, IO]:
+    ) -> Path:
         """
         Download this file. By default, the file is saved in the current working directory with its
-        original filename as reported by Telegram. If the file has no filename, it the file ID will
-        be used as filename. If a :paramref:`custom_path` is supplied, it will be saved to that
-        path instead. If :paramref:`out` is defined, the file contents will be saved to that object
-        using the :obj:`out.write<io.BufferedWriter.write>` method.
+        original filename as reported by Telegram. If the file has no filename, the file ID will
+        be used as filename. If :paramref:`custom_path` is supplied as a :obj:`str` or
+        :obj:`pathlib.Path`, it will be saved to that path.
 
         Note:
-            * :paramref:`custom_path` and :paramref:`out` are mutually exclusive.
-            * If neither :paramref:`custom_path` nor :paramref:`out` is provided and
-              :attr:`file_path` is the path of a local file (which is the case when a Bot API
-              Server is running in local mode), this method will just return the path.
+            If :paramref:`custom_path` isn't provided and :attr:`file_path` is the path of a
+              local file (which is the case when a Bot API Server is running in local mode), this
+              method will just return the path.
+
+            The only exception to this are encrypted files (e.g. a passport file). For these, a
+              file with the prefix `decrypted_` will be created in the same directory as the
+              original file in order to decrypt the file without changing the existing one
+              in-place.
+
 
         .. versionchanged:: 20.0
 
             * :paramref:`custom_path` parameter now also accepts :class:`pathlib.Path` as argument.
             * Returns :class:`pathlib.Path` object in cases where previously a :obj:`str` was
               returned.
+            * This method was previously called ``download``. It was split into
+              :meth:`download_to_memory` and :meth:`download_to_object`.
+
 
         Args:
-            custom_path (:class:`pathlib.Path` | :obj:`str`, optional): Custom path.
-            out (:obj:`io.BufferedWriter`, optional): A file-like object. Must be opened for
-                writing in binary mode, if applicable.
+            custom_path (:class:`pathlib.Path` | :obj:`str` , optional): The path where the file
+                will be saved to. If not specified, will be saved in the current working directory.
             read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to
                 :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to
                 :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.
@@ -143,32 +165,22 @@ class File(TelegramObject):
                 :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.
 
         Returns:
-            :class:`pathlib.Path` | :obj:`io.BufferedWriter`: The same object as :paramref:`out` if
-            specified. Otherwise, returns the filename downloaded to or the file path of the
-            local file.
-
-        Raises:
-            ValueError: If both :paramref:`custom_path` and :paramref:`out` are passed.
+            :class:`pathlib.Path`: Returns the Path object the file was downloaded to.
 
         """
-        if custom_path is not None and out is not None:
-            raise ValueError("`custom_path` and `out` are mutually exclusive")
-
         local_file = is_local_file(self.file_path)
         url = None if local_file else self._get_encoded_url()
-        path = Path(self.file_path) if local_file else None
 
-        if out:
-            if local_file:
-                buf = path.read_bytes()
+        # if _credentials exists we want to decrypt the file
+        if local_file and self._credentials:
+            file_to_decrypt = Path(self.file_path)
+            buf = self._prepare_decrypt(file_to_decrypt.read_bytes())
+            if custom_path is not None:
+                path = Path(custom_path)
             else:
-                buf = await self.get_bot().request.retrieve(url)
-                if self._credentials:
-                    buf = decrypt(
-                        b64decode(self._credentials.secret), b64decode(self._credentials.hash), buf
-                    )
-            out.write(buf)
-            return out
+                path = Path(str(file_to_decrypt.parent) + "/decrypted_" + file_to_decrypt.name)
+            path.write_bytes(buf)
+            return path
 
         if custom_path is not None and local_file:
             shutil.copyfile(self.file_path, str(custom_path))
@@ -191,20 +203,58 @@ class File(TelegramObject):
             pool_timeout=pool_timeout,
         )
         if self._credentials:
-            buf = decrypt(
-                b64decode(self._credentials.secret), b64decode(self._credentials.hash), buf
-            )
+            buf = self._prepare_decrypt(buf)
         filename.write_bytes(buf)
         return filename
 
-    def _get_encoded_url(self) -> str:
-        """Convert any UTF-8 char in :obj:`File.file_path` into a url encoded ASCII string."""
-        sres = urllib_parse.urlsplit(str(self.file_path))
-        return urllib_parse.urlunsplit(
-            urllib_parse.SplitResult(
-                sres.scheme, sres.netloc, urllib_parse.quote(sres.path), sres.query, sres.fragment
+    async def download_to_object(
+        self,
+        out: BinaryIO,
+        read_timeout: ODVInput[float] = DEFAULT_NONE,
+        write_timeout: ODVInput[float] = DEFAULT_NONE,
+        connect_timeout: ODVInput[float] = DEFAULT_NONE,
+        pool_timeout: ODVInput[float] = DEFAULT_NONE,
+    ) -> None:
+        """
+        Download this file into memory. :paramref:`out` needs to be supplied with a
+        :obj:`io.BufferedIOBase`, the file contents will be saved to that object using the
+        :obj:`out.write<io.BufferedIOBase.write>` method.
+
+        .. versionadded:: 20.0
+
+
+        Args:
+            out (:obj:`io.BufferedIOBase`): A file-like object. Must be opened for writing in
+                binary mode.
+            read_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to
+                :paramref:`telegram.request.BaseRequest.post.read_timeout`. Defaults to
+                :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.
+            write_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to
+                :paramref:`telegram.request.BaseRequest.post.write_timeout`. Defaults to
+                :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.
+            connect_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to
+                :paramref:`telegram.request.BaseRequest.post.connect_timeout`. Defaults to
+                :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.
+            pool_timeout (:obj:`float` | :obj:`None`, optional): Value to pass to
+                :paramref:`telegram.request.BaseRequest.post.pool_timeout`. Defaults to
+                :attr:`~telegram.request.BaseRequest.DEFAULT_NONE`.
+        """
+        local_file = is_local_file(self.file_path)
+        url = None if local_file else self._get_encoded_url()
+        path = Path(self.file_path) if local_file else None
+        if local_file:
+            buf = path.read_bytes()
+        else:
+            buf = await self.get_bot().request.retrieve(
+                url,
+                read_timeout=read_timeout,
+                write_timeout=write_timeout,
+                connect_timeout=connect_timeout,
+                pool_timeout=pool_timeout,
             )
-        )
+        if self._credentials:
+            buf = self._prepare_decrypt(buf)
+        out.write(buf)
 
     async def download_as_bytearray(self, buf: bytearray = None) -> bytearray:
         """Download this file and return it as a bytearray.
@@ -219,10 +269,15 @@ class File(TelegramObject):
         """
         if buf is None:
             buf = bytearray()
+
         if is_local_file(self.file_path):
-            buf.extend(Path(self.file_path).read_bytes())
+            bytes_data = Path(self.file_path).read_bytes()
         else:
-            buf.extend(await self.get_bot().request.retrieve(self._get_encoded_url()))
+            bytes_data = await self.get_bot().request.retrieve(self._get_encoded_url())
+        if self._credentials:
+            buf.extend(self._prepare_decrypt(bytes_data))
+        else:
+            buf.extend(bytes_data)
         return buf
 
     def set_credentials(self, credentials: "FileCredentials") -> None:

telegram/_files/inputfile.py

@@ -20,10 +20,10 @@
 
 import logging
 import mimetypes
-from pathlib import Path
 from typing import IO, Optional, Union
 from uuid import uuid4
 
+from telegram._utils.files import load_file
 from telegram._utils.types import FieldTuple
 
 _DEFAULT_MIME_TYPE = "application/octet-stream"
@@ -75,15 +75,10 @@ class InputFile:
         elif isinstance(obj, str):
             self.input_file_content = obj.encode("utf-8")
         else:
-            self.input_file_content = obj.read()
-        self.attach_name: Optional[str] = "attached" + uuid4().hex if attach else None
+            reported_filename, self.input_file_content = load_file(obj)
+            filename = filename or reported_filename
 
-        if (
-            not filename
-            and hasattr(obj, "name")
-            and not isinstance(obj.name, int)  # type: ignore[union-attr]
-        ):
-            filename = Path(obj.name).name  # type: ignore[union-attr]
+        self.attach_name: Optional[str] = "attached" + uuid4().hex if attach else None
 
         if filename:
             self.mimetype = mimetypes.guess_type(filename, strict=False)[0] or _DEFAULT_MIME_TYPE

telegram/_files/inputmedia.py

@@ -48,20 +48,15 @@ class InputMedia(TelegramObject):
         media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
             :class:`telegram.Animation` |  :class:`telegram.Audio` | \
             :class:`telegram.Document` | :class:`telegram.PhotoSize` | \
-            :class:`telegram.Video`):
-            File to send. Pass a file_id to send a file that exists on the Telegram servers
-            (recommended), pass an HTTP URL for Telegram to get a file from the Internet.
+            :class:`telegram.Video`): File to send.
+            |fileinputnopath|
             Lastly you can pass an existing telegram media object of the corresponding type
             to send.
         caption (:obj:`str`, optional): Caption of the media to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
+        parse_mode (:obj:`str`, optional): |parse_mode|
 
     Attributes:
         type (:obj:`str`): Type of the input media.
@@ -81,25 +76,23 @@ class InputMedia(TelegramObject):
         caption: str = None,
         caption_entities: Union[List[MessageEntity], Tuple[MessageEntity, ...]] = None,
         parse_mode: ODVInput[str] = DEFAULT_NONE,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
         self.type = media_type
         self.media = media
         self.caption = caption
         self.caption_entities = caption_entities
         self.parse_mode = parse_mode
 
-    def to_dict(self) -> JSONDict:
-        """See :meth:`telegram.TelegramObject.to_dict`."""
-        data = super().to_dict()
-
-        if self.caption_entities:
-            data["caption_entities"] = [ce.to_dict() for ce in self.caption_entities]
-
-        return data
-
     @staticmethod
     def _parse_thumb_input(thumb: Optional[FileInput]) -> Optional[Union[str, InputFile]]:
-        return parse_file_input(thumb, attach=True) if thumb is not None else thumb
+        # We use local_mode=True because we don't have access to the actual setting and want
+        # things to work in local mode.
+        return (
+            parse_file_input(thumb, attach=True, local_mode=True) if thumb is not None else thumb
+        )
 
 
 class InputMediaAnimation(InputMedia):
@@ -112,10 +105,8 @@ class InputMediaAnimation(InputMedia):
 
     Args:
         media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
-            :class:`telegram.Animation`): File to send. Pass a
-            file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP
-            URL for Telegram to get a file from the Internet. Lastly you can pass an existing
-            :class:`telegram.Animation` object to send.
+            :class:`telegram.Animation`): File to send. |fileinputnopath|
+            Lastly you can pass an existing :class:`telegram.Animation` object to send.
 
             .. versionchanged:: 13.2
                Accept :obj:`bytes` as input.
@@ -123,25 +114,17 @@ class InputMediaAnimation(InputMedia):
             new file. Convenience parameter, useful e.g. when sending files generated by the
             :obj:`tempfile` module.
 
-                .. versionadded:: 13.1
-        thumb (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, optional): 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.
+            .. versionadded:: 13.1
+        thumb (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | :obj:`str`, \
+                optional): |thumbdocstringnopath|
 
             .. versionchanged:: 13.2
                Accept :obj:`bytes` as input.
         caption (:obj:`str`, optional): Caption of the animation to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
         width (:obj:`int`, optional): Animation width.
         height (:obj:`int`, optional): Animation height.
         duration (:obj:`int`, optional): Animation duration in seconds.
@@ -173,6 +156,8 @@ class InputMediaAnimation(InputMedia):
         duration: int = None,
         caption_entities: Union[List[MessageEntity], Tuple[MessageEntity, ...]] = None,
         filename: str = None,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         if isinstance(media, Animation):
             width = media.width if width is None else width
@@ -180,9 +165,18 @@ class InputMediaAnimation(InputMedia):
             duration = media.duration if duration is None else duration
             media = media.file_id
         else:
-            media = parse_file_input(media, filename=filename, attach=True)
+            # We use local_mode=True because we don't have access to the actual setting and want
+            # things to work in local mode.
+            media = parse_file_input(media, filename=filename, attach=True, local_mode=True)
 
-        super().__init__(InputMediaType.ANIMATION, media, caption, caption_entities, parse_mode)
+        super().__init__(
+            InputMediaType.ANIMATION,
+            media,
+            caption,
+            caption_entities,
+            parse_mode,
+            api_kwargs=api_kwargs,
+        )
         self.thumb = self._parse_thumb_input(thumb)
         self.width = width
         self.height = height
@@ -194,10 +188,8 @@ class InputMediaPhoto(InputMedia):
 
     Args:
         media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
-            :class:`telegram.PhotoSize`): File to send. Pass a
-            file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP
-            URL for Telegram to get a file from the Internet. Lastly you can pass an existing
-            :class:`telegram.PhotoSize` object to send.
+            :class:`telegram.PhotoSize`): File to send. |fileinputnopath|
+            Lastly you can pass an existing :class:`telegram.PhotoSize` object to send.
 
             .. versionchanged:: 13.2
                Accept :obj:`bytes` as input.
@@ -205,16 +197,12 @@ class InputMediaPhoto(InputMedia):
             new file. Convenience parameter, useful e.g. when sending files generated by the
             :obj:`tempfile` module.
 
-                .. versionadded:: 13.1
+            .. versionadded:: 13.1
         caption (:obj:`str`, optional ): Caption of the photo to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InputMediaType.PHOTO`.
@@ -235,9 +223,20 @@ class InputMediaPhoto(InputMedia):
         parse_mode: ODVInput[str] = DEFAULT_NONE,
         caption_entities: Union[List[MessageEntity], Tuple[MessageEntity, ...]] = None,
         filename: str = None,
+        *,
+        api_kwargs: JSONDict = None,
     ):
-        media = parse_file_input(media, PhotoSize, filename=filename, attach=True)
-        super().__init__(InputMediaType.PHOTO, media, caption, caption_entities, parse_mode)
+        # We use local_mode=True because we don't have access to the actual setting and want
+        # things to work in local mode.
+        media = parse_file_input(media, PhotoSize, filename=filename, attach=True, local_mode=True)
+        super().__init__(
+            InputMediaType.PHOTO,
+            media,
+            caption,
+            caption_entities,
+            parse_mode,
+            api_kwargs=api_kwargs,
+        )
 
 
 class InputMediaVideo(InputMedia):
@@ -253,10 +252,8 @@ class InputMediaVideo(InputMedia):
 
     Args:
         media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
-            :class:`telegram.Video`): File to send. Pass a
-            file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP
-            URL for Telegram to get a file from the Internet. Lastly you can pass an existing
-            :class:`telegram.Video` object to send.
+            :class:`telegram.Video`): File to send. |fileinputnopath|
+            Lastly you can pass an existing :class:`telegram.Video` object to send.
 
             .. versionchanged:: 13.2
                Accept :obj:`bytes` as input.
@@ -264,27 +261,19 @@ class InputMediaVideo(InputMedia):
             new file. Convenience parameter, useful e.g. when sending files generated by the
             :obj:`tempfile` module.
 
-                .. versionadded:: 13.1
+            .. versionadded:: 13.1
         caption (:obj:`str`, optional): Caption of the video to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
         width (:obj:`int`, optional): Video width.
         height (:obj:`int`, optional): Video height.
         duration (:obj:`int`, optional): Video duration in seconds.
         supports_streaming (:obj:`bool`, optional): Pass :obj:`True`, if the uploaded video is
             suitable for streaming.
-        thumb (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, optional): 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.
+        thumb (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | :obj:`str`, \
+                optional): |thumbdocstringnopath|
 
             .. versionchanged:: 13.2
                Accept :obj:`bytes` as input.
@@ -319,6 +308,8 @@ class InputMediaVideo(InputMedia):
         thumb: FileInput = None,
         caption_entities: Union[List[MessageEntity], Tuple[MessageEntity, ...]] = None,
         filename: str = None,
+        *,
+        api_kwargs: JSONDict = None,
     ):
 
         if isinstance(media, Video):
@@ -327,9 +318,18 @@ class InputMediaVideo(InputMedia):
             duration = duration if duration is not None else media.duration
             media = media.file_id
         else:
-            media = parse_file_input(media, filename=filename, attach=True)
+            # We use local_mode=True because we don't have access to the actual setting and want
+            # things to work in local mode.
+            media = parse_file_input(media, filename=filename, attach=True, local_mode=True)
 
-        super().__init__(InputMediaType.VIDEO, media, caption, caption_entities, parse_mode)
+        super().__init__(
+            InputMediaType.VIDEO,
+            media,
+            caption,
+            caption_entities,
+            parse_mode,
+            api_kwargs=api_kwargs,
+        )
         self.width = width
         self.height = height
         self.duration = duration
@@ -347,11 +347,8 @@ class InputMediaAudio(InputMedia):
 
     Args:
         media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
-            :class:`telegram.Audio`):
-            File to send. Pass a
-            file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP
-            URL for Telegram to get a file from the Internet. Lastly you can pass an existing
-            :class:`telegram.Audio` object to send.
+            :class:`telegram.Audio`): File to send. |fileinputnopath|
+            Lastly you can pass an existing :class:`telegram.Audio` object to send.
 
             .. versionchanged:: 13.2
                Accept :obj:`bytes` as input.
@@ -359,26 +356,18 @@ class InputMediaAudio(InputMedia):
             new file. Convenience parameter, useful e.g. when sending files generated by the
             :obj:`tempfile` module.
 
-                .. versionadded:: 13.1
+            .. versionadded:: 13.1
         caption (:obj:`str`, optional): Caption of the audio to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
         duration (:obj:`int`): Duration of the audio in seconds as defined by sender.
         performer (:obj:`str`, optional): Performer of the audio as defined by sender or by audio
             tags.
         title (:obj:`str`, optional): Title of the audio as defined by sender or by audio tags.
-        thumb (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, optional): 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.
+        thumb (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | :obj:`str`, \
+                optional): |thumbdocstringnopath|
 
             .. versionchanged:: 13.2
                Accept :obj:`bytes` as input.
@@ -411,6 +400,8 @@ class InputMediaAudio(InputMedia):
         title: str = None,
         caption_entities: Union[List[MessageEntity], Tuple[MessageEntity, ...]] = None,
         filename: str = None,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         if isinstance(media, Audio):
             duration = media.duration if duration is None else duration
@@ -418,9 +409,18 @@ class InputMediaAudio(InputMedia):
             title = media.title if title is None else title
             media = media.file_id
         else:
-            media = parse_file_input(media, filename=filename, attach=True)
+            # We use local_mode=True because we don't have access to the actual setting and want
+            # things to work in local mode.
+            media = parse_file_input(media, filename=filename, attach=True, local_mode=True)
 
-        super().__init__(InputMediaType.AUDIO, media, caption, caption_entities, parse_mode)
+        super().__init__(
+            InputMediaType.AUDIO,
+            media,
+            caption,
+            caption_entities,
+            parse_mode,
+            api_kwargs=api_kwargs,
+        )
         self.thumb = self._parse_thumb_input(thumb)
         self.duration = duration
         self.title = title
@@ -432,10 +432,8 @@ class InputMediaDocument(InputMedia):
 
     Args:
         media (:obj:`str` | :term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | \
-            :class:`telegram.Document`): File to send. Pass a
-            file_id to send a file that exists on the Telegram servers (recommended), pass an HTTP
-            URL for Telegram to get a file from the Internet. Lastly you can pass an existing
-            :class:`telegram.Document` object to send.
+            :class:`telegram.Document`): File to send. |fileinputnopath|
+            Lastly you can pass an existing :class:`telegram.Document` object to send.
 
             .. versionchanged:: 13.2
                Accept :obj:`bytes` as input.
@@ -443,22 +441,14 @@ class InputMediaDocument(InputMedia):
             new file. Convenience parameter, useful e.g. when sending files generated by the
             :obj:`tempfile` module.
 
-                .. versionadded:: 13.1
+            .. versionadded:: 13.1
         caption (:obj:`str`, optional): Caption of the document to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
-        thumb (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path`, optional): 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.
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
+        thumb (:term:`file object` | :obj:`bytes` | :class:`pathlib.Path` | :obj:`str`, \
+                optional): |thumbdocstringnopath|
 
             .. versionchanged:: 13.2
                Accept :obj:`bytes` as input.
@@ -491,8 +481,19 @@ class InputMediaDocument(InputMedia):
         disable_content_type_detection: bool = None,
         caption_entities: Union[List[MessageEntity], Tuple[MessageEntity, ...]] = None,
         filename: str = None,
+        *,
+        api_kwargs: JSONDict = None,
     ):
-        media = parse_file_input(media, Document, filename=filename, attach=True)
-        super().__init__(InputMediaType.DOCUMENT, media, caption, caption_entities, parse_mode)
+        # We use local_mode=True because we don't have access to the actual setting and want
+        # things to work in local mode.
+        media = parse_file_input(media, Document, filename=filename, attach=True, local_mode=True)
+        super().__init__(
+            InputMediaType.DOCUMENT,
+            media,
+            caption,
+            caption_entities,
+            parse_mode,
+            api_kwargs=api_kwargs,
+        )
         self.thumb = self._parse_thumb_input(thumb)
         self.disable_content_type_detection = disable_content_type_detection

telegram/_files/location.py

@@ -18,9 +18,11 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram Location."""
 
-from typing import Any
+from typing import ClassVar
 
+from telegram import constants
 from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
 
 
 class Location(TelegramObject):
@@ -33,14 +35,14 @@ class Location(TelegramObject):
         longitude (:obj:`float`): Longitude as defined by sender.
         latitude (:obj:`float`): Latitude as defined by sender.
         horizontal_accuracy (:obj:`float`, optional): The radius of uncertainty for the location,
-            measured in meters; 0-:tg-const:`telegram.constants.LocationLimit.HORIZONTAL_ACCURACY`.
+            measured in meters; 0-:tg-const:`telegram.Location.HORIZONTAL_ACCURACY`.
         live_period (:obj:`int`, optional): Time relative to the message sending date, during which
             the location can be updated, in seconds. For active live locations only.
         heading (:obj:`int`, optional): The direction in which user is moving, in degrees;
-            1-:tg-const:`telegram.constants.LocationLimit.HEADING`. For active live locations only.
+            :tg-const:`telegram.Location.MIN_HEADING`-:tg-const:`telegram.Location.MAX_HEADING`.
+            For active live locations only.
         proximity_alert_radius (:obj:`int`, optional): Maximum distance for proximity alerts about
             approaching another chat member, in meters. For sent live locations only.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         longitude (:obj:`float`): Longitude as defined by sender.
@@ -73,8 +75,10 @@ class Location(TelegramObject):
         live_period: int = None,
         heading: int = None,
         proximity_alert_radius: int = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
         # Required
         self.longitude = longitude
         self.latitude = latitude
@@ -88,3 +92,19 @@ class Location(TelegramObject):
         )
 
         self._id_attrs = (self.longitude, self.latitude)
+
+    HORIZONTAL_ACCURACY: ClassVar[int] = constants.LocationLimit.HORIZONTAL_ACCURACY
+    """:const:`telegram.constants.LocationLimit.HORIZONTAL_ACCURACY`
+
+    .. versionadded:: 20.0
+    """
+    MIN_HEADING: ClassVar[int] = constants.LocationLimit.MIN_HEADING
+    """:const:`telegram.constants.LocationLimit.MIN_HEADING`
+
+    .. versionadded:: 20.0
+    """
+    MAX_HEADING: ClassVar[int] = constants.LocationLimit.MAX_HEADING
+    """:const:`telegram.constants.LocationLimit.MAX_HEADING`
+
+    .. versionadded:: 20.0
+    """

telegram/_files/photosize.py

@@ -18,12 +18,8 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram PhotoSize."""
 
-from typing import TYPE_CHECKING, Any
-
 from telegram._files._basemedium import _BaseMedium
-
-if TYPE_CHECKING:
-    from telegram import Bot
+from telegram._utils.types import JSONDict
 
 
 class PhotoSize(_BaseMedium):
@@ -41,8 +37,6 @@ class PhotoSize(_BaseMedium):
         width (:obj:`int`): Photo width.
         height (:obj:`int`): Photo height.
         file_size (:obj:`int`, optional): File size in bytes.
-        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         file_id (:obj:`str`): Identifier for this file.
@@ -52,7 +46,7 @@ class PhotoSize(_BaseMedium):
         width (:obj:`int`): Photo width.
         height (:obj:`int`): Photo height.
         file_size (:obj:`int`): Optional. File size in bytes.
-        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
+
 
     """
 
@@ -65,11 +59,14 @@ class PhotoSize(_BaseMedium):
         width: int,
         height: int,
         file_size: int = None,
-        bot: "Bot" = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         super().__init__(
-            file_id=file_id, file_unique_id=file_unique_id, file_size=file_size, bot=bot
+            file_id=file_id,
+            file_unique_id=file_unique_id,
+            file_size=file_size,
+            api_kwargs=api_kwargs,
         )
         # Required
         self.width = width

telegram/_files/sticker.py

@@ -18,7 +18,7 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains objects that represent stickers."""
 
-from typing import TYPE_CHECKING, Any, ClassVar, List, Optional
+from typing import TYPE_CHECKING, ClassVar, List, Optional
 
 from telegram import constants
 from telegram._files._basethumbedmedium import _BaseThumbedMedium
@@ -67,16 +67,15 @@ class Sticker(_BaseThumbedMedium):
         mask_position (:class:`telegram.MaskPosition`, optional): For mask stickers, the
             position where the mask should be placed.
         file_size (:obj:`int`, optional): File size in bytes.
-        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
+
         premium_animation (:class:`telegram.File`, optional): For premium regular stickers,
             premium animation for the sticker.
 
             .. versionadded:: 20.0
-        custom_emoji (:obj:`str`, optional): For custom emoji stickers, unique identifier of the
+        custom_emoji_id (:obj:`str`, optional): For custom emoji stickers, unique identifier of the
             custom emoji.
 
             .. versionadded:: 20.0
-        _kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         file_id (:obj:`str`): Identifier for this file.
@@ -101,12 +100,12 @@ class Sticker(_BaseThumbedMedium):
         mask_position (:class:`telegram.MaskPosition`): Optional. For mask stickers, the position
             where the mask should be placed.
         file_size (:obj:`int`): Optional. File size in bytes.
-        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
+
         premium_animation (:class:`telegram.File`): Optional. For premium regular stickers,
             premium animation for the sticker.
 
             .. versionadded:: 20.0
-        custom_emoji (:obj:`str`): Optional. For custom emoji stickers, unique identifier of the
+        custom_emoji_id (:obj:`str`): Optional. For custom emoji stickers, unique identifier of the
             custom emoji.
 
             .. versionadded:: 20.0
@@ -139,17 +138,17 @@ class Sticker(_BaseThumbedMedium):
         file_size: int = None,
         set_name: str = None,
         mask_position: "MaskPosition" = None,
-        bot: "Bot" = None,
         premium_animation: "File" = None,
         custom_emoji_id: str = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         super().__init__(
             file_id=file_id,
             file_unique_id=file_unique_id,
             file_size=file_size,
             thumb=thumb,
-            bot=bot,
+            api_kwargs=api_kwargs,
         )
         # Required
         self.width = width
@@ -183,7 +182,7 @@ class Sticker(_BaseThumbedMedium):
         data["mask_position"] = MaskPosition.de_json(data.get("mask_position"), bot)
         data["premium_animation"] = File.de_json(data.get("premium_animation"), bot)
 
-        return cls(bot=bot, **data)
+        return super().de_json(data=data, bot=bot)
 
 
 class StickerSet(TelegramObject):
@@ -251,8 +250,10 @@ class StickerSet(TelegramObject):
         is_video: bool,
         sticker_type: str,
         thumb: PhotoSize = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
         self.name = name
         self.title = title
         self.is_animated = is_animated
@@ -273,15 +274,13 @@ class StickerSet(TelegramObject):
         data["thumb"] = PhotoSize.de_json(data.get("thumb"), bot)
         data["stickers"] = Sticker.de_list(data.get("stickers"), bot)
 
-        return cls(bot=bot, **data)
+        api_kwargs = {}
+        # This is a deprecated field that TG still returns for backwards compatibility
+        # Let's filter it out to speed up the de-json process
+        if "contains_masks" in data:
+            api_kwargs["contains_masks"] = data.pop("contains_masks")
 
-    def to_dict(self) -> JSONDict:
-        """See :meth:`telegram.TelegramObject.to_dict`."""
-        data = super().to_dict()
-
-        data["stickers"] = [s.to_dict() for s in data.get("stickers")]  # type: ignore[union-attr]
-
-        return data
+        return super()._de_json(data=data, bot=bot, api_kwargs=api_kwargs)
 
 
 class MaskPosition(TelegramObject):
@@ -324,20 +323,19 @@ class MaskPosition(TelegramObject):
     CHIN: ClassVar[str] = constants.MaskPosition.CHIN
     """:const:`telegram.constants.MaskPosition.CHIN`"""
 
-    def __init__(self, point: str, x_shift: float, y_shift: float, scale: float, **_kwargs: Any):
+    def __init__(
+        self,
+        point: str,
+        x_shift: float,
+        y_shift: float,
+        scale: float,
+        *,
+        api_kwargs: JSONDict = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
         self.point = point
         self.x_shift = x_shift
         self.y_shift = y_shift
         self.scale = scale
 
         self._id_attrs = (self.point, self.x_shift, self.y_shift, self.scale)
-
-    @classmethod
-    def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["MaskPosition"]:
-        """See :meth:`telegram.TelegramObject.de_json`."""
-        data = cls._parse_data(data)
-
-        if data is None:
-            return None
-
-        return cls(**data)

telegram/_files/venue.py

@@ -18,7 +18,7 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram Venue."""
 
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Optional
 
 from telegram._files.location import Location
 from telegram._telegramobject import TelegramObject
@@ -49,7 +49,6 @@ class Venue(TelegramObject):
         google_place_type (:obj:`str`, optional): Google Places type of the venue. (See
             `supported types <https://developers.google.com/maps/documentation/places/web-service\
             /supported_types>`_.)
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         location (:class:`telegram.Location`): Venue location.
@@ -81,8 +80,11 @@ class Venue(TelegramObject):
         foursquare_type: str = None,
         google_place_id: str = None,
         google_place_type: str = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
+
         # Required
         self.location = location
         self.title = title
@@ -105,4 +107,4 @@ class Venue(TelegramObject):
 
         data["location"] = Location.de_json(data.get("location"), bot)
 
-        return cls(**data)
+        return super().de_json(data=data, bot=bot)

telegram/_files/video.py

@@ -18,13 +18,9 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram Video."""
 
-from typing import TYPE_CHECKING, Any
-
 from telegram._files._basethumbedmedium import _BaseThumbedMedium
 from telegram._files.photosize import PhotoSize
-
-if TYPE_CHECKING:
-    from telegram import Bot
+from telegram._utils.types import JSONDict
 
 
 class Video(_BaseThumbedMedium):
@@ -46,8 +42,6 @@ class Video(_BaseThumbedMedium):
         file_name (:obj:`str`, optional): Original filename as defined by sender.
         mime_type (:obj:`str`, optional): MIME type of a file as defined by sender.
         file_size (:obj:`int`, optional): File size in bytes.
-        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         file_id (:obj:`str`): Identifier for this file.
@@ -61,7 +55,7 @@ class Video(_BaseThumbedMedium):
         file_name (:obj:`str`): Optional. Original filename as defined by sender.
         mime_type (:obj:`str`): Optional. MIME type of a file as defined by sender.
         file_size (:obj:`int`): Optional. File size in bytes.
-        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
+
 
     """
 
@@ -77,16 +71,16 @@ class Video(_BaseThumbedMedium):
         thumb: PhotoSize = None,
         mime_type: str = None,
         file_size: int = None,
-        bot: "Bot" = None,
         file_name: str = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         super().__init__(
             file_id=file_id,
             file_unique_id=file_unique_id,
             file_size=file_size,
             thumb=thumb,
-            bot=bot,
+            api_kwargs=api_kwargs,
         )
         # Required
         self.width = width

telegram/_files/videonote.py

@@ -18,13 +18,9 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram VideoNote."""
 
-from typing import TYPE_CHECKING, Any
-
 from telegram._files._basethumbedmedium import _BaseThumbedMedium
 from telegram._files.photosize import PhotoSize
-
-if TYPE_CHECKING:
-    from telegram import Bot
+from telegram._utils.types import JSONDict
 
 
 class VideoNote(_BaseThumbedMedium):
@@ -44,8 +40,6 @@ class VideoNote(_BaseThumbedMedium):
         duration (:obj:`int`): Duration of the video in seconds as defined by sender.
         thumb (:class:`telegram.PhotoSize`, optional): Video thumbnail.
         file_size (:obj:`int`, optional): File size in bytes.
-        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         file_id (:obj:`str`): Identifier for this file.
@@ -56,7 +50,6 @@ class VideoNote(_BaseThumbedMedium):
         duration (:obj:`int`): Duration of the video in seconds as defined by sender.
         thumb (:class:`telegram.PhotoSize`): Optional. Video thumbnail.
         file_size (:obj:`int`): Optional. File size in bytes.
-        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
 
     """
 
@@ -70,15 +63,15 @@ class VideoNote(_BaseThumbedMedium):
         duration: int,
         thumb: PhotoSize = None,
         file_size: int = None,
-        bot: "Bot" = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         super().__init__(
             file_id=file_id,
             file_unique_id=file_unique_id,
             file_size=file_size,
             thumb=thumb,
-            bot=bot,
+            api_kwargs=api_kwargs,
         )
         # Required
         self.length = length

telegram/_files/voice.py

@@ -18,12 +18,8 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram Voice."""
 
-from typing import TYPE_CHECKING, Any
-
 from telegram._files._basemedium import _BaseMedium
-
-if TYPE_CHECKING:
-    from telegram import Bot
+from telegram._utils.types import JSONDict
 
 
 class Voice(_BaseMedium):
@@ -41,8 +37,6 @@ class Voice(_BaseMedium):
         duration (:obj:`int`, optional): Duration of the audio in seconds as defined by sender.
         mime_type (:obj:`str`, optional): MIME type of the file as defined by sender.
         file_size (:obj:`int`, optional): File size in bytes.
-        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         file_id (:obj:`str`): Identifier for this file.
@@ -52,7 +46,6 @@ class Voice(_BaseMedium):
         duration (:obj:`int`): Duration of the audio in seconds as defined by sender.
         mime_type (:obj:`str`): Optional. MIME type of the file as defined by sender.
         file_size (:obj:`int`): Optional. File size in bytes.
-        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
 
     """
 
@@ -65,14 +58,14 @@ class Voice(_BaseMedium):
         duration: int,
         mime_type: str = None,
         file_size: int = None,
-        bot: "Bot" = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         super().__init__(
             file_id=file_id,
             file_unique_id=file_unique_id,
             file_size=file_size,
-            bot=bot,
+            api_kwargs=api_kwargs,
         )
         # Required
         self.duration = duration

telegram/_forcereply.py

@@ -18,9 +18,11 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram ForceReply."""
 
-from typing import Any
+from typing import ClassVar
 
+from telegram import constants
 from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
 
 
 class ForceReply(TelegramObject):
@@ -47,12 +49,13 @@ class ForceReply(TelegramObject):
                original message.
 
         input_field_placeholder (:obj:`str`, optional): The placeholder to be shown in the input
-            field when the reply is active; 1-64 characters.
+            field when the reply is active;
+            :tg-const:`telegram.ForceReply.MIN_INPUT_FIELD_PLACEHOLDER`-
+            :tg-const:`telegram.ForceReply.MAX_INPUT_FIELD_PLACEHOLDER`
+            characters.
 
             .. versionadded:: 13.7
 
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
-
     Attributes:
         force_reply (:obj:`True`): Shows reply interface to the user, as if they manually selected
             the bots message and tapped 'Reply'.
@@ -70,10 +73,23 @@ class ForceReply(TelegramObject):
         self,
         selective: bool = None,
         input_field_placeholder: str = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
         self.force_reply = True
         self.selective = selective
         self.input_field_placeholder = input_field_placeholder
 
         self._id_attrs = (self.selective,)
+
+    MIN_INPUT_FIELD_PLACEHOLDER: ClassVar[int] = constants.ReplyLimit.MIN_INPUT_FIELD_PLACEHOLDER
+    """:const:`telegram.constants.ReplyLimit.MIN_INPUT_FIELD_PLACEHOLDER`
+
+    .. versionadded:: 20.0
+    """
+    MAX_INPUT_FIELD_PLACEHOLDER: ClassVar[int] = constants.ReplyLimit.MAX_INPUT_FIELD_PLACEHOLDER
+    """:const:`telegram.constants.ReplyLimit.MAX_INPUT_FIELD_PLACEHOLDER`
+
+    .. versionadded:: 20.0
+    """

telegram/_forumtopic.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2022
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains objects related to Telegram forum topics."""
+
+from telegram._telegramobject import TelegramObject
+from telegram._utils.types import JSONDict
+
+
+class ForumTopic(TelegramObject):
+    """
+    This object represents a forum topic.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`message_thread_id`, :attr:`name` and :attr:`icon_color`
+    are equal.
+
+    .. versionadded:: 20.0
+
+    Args:
+        message_thread_id (:obj:`int`): Unique identifier of the forum topic
+        name (:obj:`str`): Name of the topic
+        icon_color (:obj:`int`): Color of the topic icon in RGB format
+        icon_custom_emoji_id (:obj:`str`, optional): Unique identifier of the custom emoji shown
+            as the topic icon.
+
+    Attributes:
+        message_thread_id (:obj:`int`): Unique identifier of the forum topic
+        name (:obj:`str`): Name of the topic
+        icon_color (:obj:`int`): Color of the topic icon in RGB format
+        icon_custom_emoji_id (:obj:`str`): Optional. Unique identifier of the custom emoji shown
+            as the topic icon.
+    """
+
+    __slots__ = ("message_thread_id", "name", "icon_color", "icon_custom_emoji_id")
+
+    def __init__(
+        self,
+        message_thread_id: int,
+        name: str,
+        icon_color: int,
+        icon_custom_emoji_id: str = None,
+        *,
+        api_kwargs: JSONDict = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        self.message_thread_id = message_thread_id
+        self.name = name
+        self.icon_color = icon_color
+        self.icon_custom_emoji_id = icon_custom_emoji_id
+
+        self._id_attrs = (self.message_thread_id, self.name, self.icon_color)
+
+
+class ForumTopicCreated(TelegramObject):
+    """
+    This object represents the content of a service message about a new forum topic created in
+    the chat.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`name` and :attr:`icon_color` are equal.
+
+    .. versionadded:: 20.0
+
+    Args:
+        name (:obj:`str`): Name of the topic
+        icon_color (:obj:`int`): Color of the topic icon in RGB format
+        icon_custom_emoji_id (:obj:`str`, optional): Unique identifier of the custom emoji shown
+            as the topic icon.
+
+    Attributes:
+        name (:obj:`str`): Name of the topic
+        icon_color (:obj:`int`): Color of the topic icon in RGB format
+        icon_custom_emoji_id (:obj:`str`): Optional. Unique identifier of the custom emoji shown
+            as the topic icon.
+    """
+
+    __slots__ = ("name", "icon_color", "icon_custom_emoji_id")
+
+    def __init__(
+        self,
+        name: str,
+        icon_color: int,
+        icon_custom_emoji_id: str = None,
+        *,
+        api_kwargs: JSONDict = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
+        self.name = name
+        self.icon_color = icon_color
+        self.icon_custom_emoji_id = icon_custom_emoji_id
+
+        self._id_attrs = (self.name, self.icon_color)
+
+
+class ForumTopicClosed(TelegramObject):
+    """
+    This object represents a service message about a forum topic closed in the chat.
+    Currently holds no information.
+
+    .. versionadded:: 20.0
+    """
+
+    __slots__ = ()
+
+
+class ForumTopicReopened(TelegramObject):
+    """
+    This object represents a service message about a forum topic reopened in the chat.
+    Currently holds no information.
+
+    .. versionadded:: 20.0
+    """
+
+    __slots__ = ()

telegram/_games/game.py

@@ -19,7 +19,7 @@
 """This module contains an object that represents a Telegram Game."""
 
 import sys
-from typing import TYPE_CHECKING, Any, Dict, List, Optional
+from typing import TYPE_CHECKING, Dict, List, Optional
 
 from telegram._files.animation import Animation
 from telegram._files.photosize import PhotoSize
@@ -48,7 +48,7 @@ class Game(TelegramObject):
             game message. Can be automatically edited to include current high scores for the game
             when the bot calls :meth:`telegram.Bot.set_game_score`, or manually edited
             using :meth:`telegram.Bot.edit_message_text`.
-            0-:tg-const:`telegram.constants.MessageLimit.TEXT_LENGTH` characters.
+            0-:tg-const:`telegram.constants.MessageLimit.MAX_TEXT_LENGTH` characters.
         text_entities (List[:class:`telegram.MessageEntity`], optional): Special entities that
             appear in text, such as usernames, URLs, bot commands, etc.
         animation (:class:`telegram.Animation`, optional): Animation that will be displayed in the
@@ -88,8 +88,10 @@ class Game(TelegramObject):
         text: str = None,
         text_entities: List[MessageEntity] = None,
         animation: Animation = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
         # Required
         self.title = title
         self.description = description
@@ -113,17 +115,7 @@ class Game(TelegramObject):
         data["text_entities"] = MessageEntity.de_list(data.get("text_entities"), bot)
         data["animation"] = Animation.de_json(data.get("animation"), bot)
 
-        return cls(**data)
-
-    def to_dict(self) -> JSONDict:
-        """See :meth:`telegram.TelegramObject.to_dict`."""
-        data = super().to_dict()
-
-        data["photo"] = [p.to_dict() for p in self.photo]
-        if self.text_entities:
-            data["text_entities"] = [x.to_dict() for x in self.text_entities]
-
-        return data
+        return super().de_json(data=data, bot=bot)
 
     def parse_text_entity(self, entity: MessageEntity) -> str:
         """Returns the text from a given :class:`telegram.MessageEntity`.

telegram/_games/gamehighscore.py

@@ -48,7 +48,8 @@ class GameHighScore(TelegramObject):
 
     __slots__ = ("position", "user", "score")
 
-    def __init__(self, position: int, user: User, score: int):
+    def __init__(self, position: int, user: User, score: int, *, api_kwargs: JSONDict = None):
+        super().__init__(api_kwargs=api_kwargs)
         self.position = position
         self.user = user
         self.score = score
@@ -65,4 +66,4 @@ class GameHighScore(TelegramObject):
 
         data["user"] = User.de_json(data.get("user"), bot)
 
-        return cls(**data)
+        return super().de_json(data=data, bot=bot)

telegram/_inline/inlinekeyboardbutton.py

@@ -18,8 +18,9 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram InlineKeyboardButton."""
 
-from typing import TYPE_CHECKING, Any, Optional, Union
+from typing import TYPE_CHECKING, ClassVar, Optional, Union
 
+from telegram import constants
 from telegram._games.callbackgame import CallbackGame
 from telegram._loginurl import LoginUrl
 from telegram._telegramobject import TelegramObject
@@ -62,9 +63,11 @@ class InlineKeyboardButton(TelegramObject):
 
         * After Bot API 6.1, only ``HTTPS`` links will be allowed in :paramref:`login_url`.
 
-    .. seealso:: `Inline Keyboard Example 1 <examples.inlinekeyboard.html>`_,
-        `Inline Keyboard Example 2 <examples.inlinekeyboard2.html>`_,
-        :class:`telegram.InlineKeyboardMarkup`
+    Examples:
+        * :any:`Inline Keyboard 1 <examples.inlinekeyboard>`
+        * :any:`Inline Keyboard 2 <examples.inlinekeyboard2>`
+
+    .. seealso:: :class:`telegram.InlineKeyboardMarkup`
 
     .. versionchanged:: 20.0
        :attr:`web_app` is considered as well when comparing objects of this type in terms of
@@ -84,12 +87,17 @@ class InlineKeyboardButton(TelegramObject):
             Caution:
                 Only ``HTTPS`` links are allowed after Bot API 6.1.
         callback_data (:obj:`str` | :obj:`object`, optional): Data to be sent in a callback query
-            to the bot when button is pressed, UTF-8 1-64 bytes. If the bot instance allows
-            arbitrary callback data, anything can be passed.
+            to the bot when button is pressed, UTF-8
+            :tg-const:`telegram.InlineKeyboardButton.MIN_CALLBACK_DATA`-
+            :tg-const:`telegram.InlineKeyboardButton.MAX_CALLBACK_DATA` bytes.
+            If the bot instance allows arbitrary callback data, anything can be passed.
 
             Tip:
                 The value entered here will be available in :attr:`telegram.CallbackQuery.data`.
 
+            .. seealso:: `Arbitrary callback_data <https://github.com/\
+                python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>`_
+
         web_app (:obj:`telegram.WebAppInfo`, optional): Description of the `Web App
             <https://core.telegram.org/bots/webapps>`_  that will be launched when the user presses
             the button. The Web App will be able to send an arbitrary message on behalf of the user
@@ -115,7 +123,6 @@ class InlineKeyboardButton(TelegramObject):
         pay (:obj:`bool`, optional): Specify :obj:`True`, to send a Pay button. This type of button
             must always be the `first` button in the first row and can only be used in invoice
             messages.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         text (:obj:`str`): Label text on the button.
@@ -131,7 +138,9 @@ class InlineKeyboardButton(TelegramObject):
             Caution:
                 Only ``HTTPS`` links are allowed after Bot API 6.1.
         callback_data (:obj:`str` | :obj:`object`): Optional. Data to be sent in a callback query
-            to the bot when button is pressed, UTF-8 1-64 bytes.
+            to the bot when button is pressed, UTF-8
+            :tg-const:`telegram.InlineKeyboardButton.MIN_CALLBACK_DATA`-
+            :tg-const:`telegram.InlineKeyboardButton.MAX_CALLBACK_DATA` bytes.
         web_app (:obj:`telegram.WebAppInfo`): Optional. Description of the `Web App
             <https://core.telegram.org/bots/webapps>`_  that will be launched when the user presses
             the button. The Web App will be able to send an arbitrary message on behalf of the user
@@ -174,8 +183,10 @@ class InlineKeyboardButton(TelegramObject):
         pay: bool = None,
         login_url: LoginUrl = None,
         web_app: WebAppInfo = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
         # Required
         self.text = text
 
@@ -216,7 +227,7 @@ class InlineKeyboardButton(TelegramObject):
         data["web_app"] = WebAppInfo.de_json(data.get("web_app"), bot)
         data["callback_game"] = CallbackGame.de_json(data.get("callback_game"), bot)
 
-        return cls(**data)
+        return super().de_json(data=data, bot=bot)
 
     def update_callback_data(self, callback_data: Union[str, object]) -> None:
         """
@@ -230,3 +241,14 @@ class InlineKeyboardButton(TelegramObject):
         """
         self.callback_data = callback_data
         self._set_id_attrs()
+
+    MIN_CALLBACK_DATA: ClassVar[int] = constants.InlineKeyboardButtonLimit.MIN_CALLBACK_DATA
+    """:const:`telegram.constants.InlineKeyboardButtonLimit.MIN_CALLBACK_DATA`
+
+    .. versionadded:: 20.0
+    """
+    MAX_CALLBACK_DATA: ClassVar[int] = constants.InlineKeyboardButtonLimit.MAX_CALLBACK_DATA
+    """:const:`telegram.constants.InlineKeyboardButtonLimit.MAX_CALLBACK_DATA`
+
+    .. versionadded:: 20.0
+    """

telegram/_inline/inlinekeyboardmarkup.py

@@ -18,7 +18,7 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram InlineKeyboardMarkup."""
 
-from typing import TYPE_CHECKING, Any, List, Optional
+from typing import TYPE_CHECKING, List, Optional
 
 from telegram._inline.inlinekeyboardbutton import InlineKeyboardButton
 from telegram._telegramobject import TelegramObject
@@ -36,13 +36,13 @@ class InlineKeyboardMarkup(TelegramObject):
     Objects of this class are comparable in terms of equality. Two objects of this class are
     considered equal, if their size of :attr:`inline_keyboard` and all the buttons are equal.
 
-    .. seealso:: `Inline Keyboard Example 1 <examples.inlinekeyboard.html>`_,
-        `Inline Keyboard Example 2 <examples.inlinekeyboard2.html>`_
+    Examples:
+        * :any:`Inline Keyboard 1 <examples.inlinekeyboard>`
+        * :any:`Inline Keyboard 2 <examples.inlinekeyboard2>`
 
     Args:
         inline_keyboard (List[List[:class:`telegram.InlineKeyboardButton`]]): List of button rows,
             each represented by a list of InlineKeyboardButton objects.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         inline_keyboard (List[List[:class:`telegram.InlineKeyboardButton`]]): List of button rows,
@@ -52,7 +52,13 @@ class InlineKeyboardMarkup(TelegramObject):
 
     __slots__ = ("inline_keyboard",)
 
-    def __init__(self, inline_keyboard: List[List[InlineKeyboardButton]], **_kwargs: Any):
+    def __init__(
+        self,
+        inline_keyboard: List[List[InlineKeyboardButton]],
+        *,
+        api_kwargs: JSONDict = None,
+    ):
+        super().__init__(api_kwargs=api_kwargs)
         if not check_keyboard_type(inline_keyboard):
             raise ValueError(
                 "The parameter `inline_keyboard` should be a list of "
@@ -63,21 +69,9 @@ class InlineKeyboardMarkup(TelegramObject):
 
         self._id_attrs = (self.inline_keyboard,)
 
-    def to_dict(self) -> JSONDict:
-        """See :meth:`telegram.TelegramObject.to_dict`."""
-        data = super().to_dict()
-
-        data["inline_keyboard"] = []
-        for inline_keyboard in self.inline_keyboard:
-            data["inline_keyboard"].append([x.to_dict() for x in inline_keyboard])
-
-        return data
-
     @classmethod
     def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["InlineKeyboardMarkup"]:
         """See :meth:`telegram.TelegramObject.de_json`."""
-        data = cls._parse_data(data)
-
         if not data:
             return None
 
@@ -102,10 +96,9 @@ class InlineKeyboardMarkup(TelegramObject):
 
         Args:
             button (:class:`telegram.InlineKeyboardButton`): The button to use in the markup
-            **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
         """
-        return cls([[button]], **kwargs)
+        return cls([[button]], **kwargs)  # type: ignore[arg-type]
 
     @classmethod
     def from_row(
@@ -120,10 +113,9 @@ class InlineKeyboardMarkup(TelegramObject):
         Args:
             button_row (List[:class:`telegram.InlineKeyboardButton`]): The button to use in the
                 markup
-            **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
         """
-        return cls([button_row], **kwargs)
+        return cls([button_row], **kwargs)  # type: ignore[arg-type]
 
     @classmethod
     def from_column(
@@ -138,11 +130,10 @@ class InlineKeyboardMarkup(TelegramObject):
         Args:
             button_column (List[:class:`telegram.InlineKeyboardButton`]): The button to use in the
                 markup
-            **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
         """
         button_grid = [[button] for button in button_column]
-        return cls(button_grid, **kwargs)
+        return cls(button_grid, **kwargs)  # type: ignore[arg-type]
 
     def __hash__(self) -> int:
         return hash(tuple(tuple(button for button in row) for row in self.inline_keyboard))

telegram/_inline/inlinequery.py

@@ -19,7 +19,7 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram InlineQuery."""
 
-from typing import TYPE_CHECKING, Any, Callable, ClassVar, Optional, Sequence, Union
+from typing import TYPE_CHECKING, Callable, ClassVar, Optional, Sequence, Union
 
 from telegram import constants
 from telegram._files.location import Location
@@ -44,16 +44,16 @@ class InlineQuery(TelegramObject):
         In Python :keyword:`from` is a reserved word use :paramref:`from_user` instead.
 
     .. versionchanged:: 20.0
-
-        * The following are now keyword-only arguments in Bot methods:
-          ``{read, write, connect, pool}_timeout``, :paramref:`answer.api_kwargs`,
-          ``auto_pagination``. Use a named argument for those,
-          and notice that some positional arguments changed position as a result.
+        The following are now keyword-only arguments in Bot methods:
+        ``{read, write, connect, pool}_timeout``, :paramref:`answer.api_kwargs`,
+        ``auto_pagination``. Use a named argument for those,
+        and notice that some positional arguments changed position as a result.
 
     Args:
         id (:obj:`str`): Unique identifier for this query.
         from_user (:class:`telegram.User`): Sender.
-        query (:obj:`str`): Text of the query (up to 256 characters).
+        query (:obj:`str`): Text of the query (up to
+            :tg-const:`telegram.InlineQuery.MAX_QUERY_LENGTH` characters).
         offset (:obj:`str`): Offset of the results to be returned, can be controlled by the bot.
         chat_type (:obj:`str`, optional): Type of the chat, from which the inline query was sent.
             Can be either :tg-const:`telegram.Chat.SENDER` for a private chat with the inline query
@@ -65,17 +65,16 @@ class InlineQuery(TelegramObject):
             .. versionadded:: 13.5
         location (:class:`telegram.Location`, optional): Sender location, only for bots that
             request user location.
-        bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         id (:obj:`str`): Unique identifier for this query.
         from_user (:class:`telegram.User`): Sender.
-        query (:obj:`str`): Text of the query (up to 256 characters).
+        query (:obj:`str`): Text of the query (up to
+            :tg-const:`telegram.InlineQuery.MAX_QUERY_LENGTH` characters).
         offset (:obj:`str`): Offset of the results to be returned, can be controlled by the bot.
         location (:class:`telegram.Location`): Optional. Sender location, only for bots that
             request user location.
-        chat_type (:obj:`str`, optional): Type of the chat, from which the inline query was sent.
+        chat_type (:obj:`str`): Optional. Type of the chat, from which the inline query was sent.
 
             .. versionadded:: 13.5
 
@@ -85,15 +84,16 @@ class InlineQuery(TelegramObject):
 
     def __init__(
         self,
-        id: str,  # pylint: disable=redefined-builtin, invalid-name
+        id: str,  # pylint: disable=redefined-builtin
         from_user: User,
         query: str,
         offset: str,
         location: Location = None,
-        bot: "Bot" = None,
         chat_type: str = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
         # Required
         self.id = id  # pylint: disable=invalid-name
         self.from_user = from_user
@@ -104,7 +104,6 @@ class InlineQuery(TelegramObject):
         self.location = location
         self.chat_type = chat_type
 
-        self.set_bot(bot)
         self._id_attrs = (self.id,)
 
     @classmethod
@@ -115,10 +114,10 @@ class InlineQuery(TelegramObject):
         if not data:
             return None
 
-        data["from_user"] = User.de_json(data.get("from"), bot)
+        data["from_user"] = User.de_json(data.pop("from", None), bot)
         data["location"] = Location.de_json(data.get("location"), bot)
 
-        return cls(bot=bot, **data)
+        return super().de_json(data=data, bot=bot)
 
     async def answer(
         self,
@@ -188,8 +187,23 @@ class InlineQuery(TelegramObject):
 
     .. versionadded:: 13.2
     """
-    MAX_SWITCH_PM_TEXT_LENGTH: ClassVar[int] = constants.InlineQueryLimit.SWITCH_PM_TEXT_LENGTH
-    """:const:`telegram.constants.InlineQueryLimit.SWITCH_PM_TEXT_LENGTH`
+    MIN_SWITCH_PM_TEXT_LENGTH: ClassVar[int] = constants.InlineQueryLimit.MIN_SWITCH_PM_TEXT_LENGTH
+    """:const:`telegram.constants.InlineQueryLimit.MIN_SWITCH_PM_TEXT_LENGTH`
+
+    .. versionadded:: 20.0
+    """
+    MAX_SWITCH_PM_TEXT_LENGTH: ClassVar[int] = constants.InlineQueryLimit.MAX_SWITCH_PM_TEXT_LENGTH
+    """:const:`telegram.constants.InlineQueryLimit.MAX_SWITCH_PM_TEXT_LENGTH`
+
+    .. versionadded:: 20.0
+    """
+    MAX_OFFSET_LENGTH: ClassVar[int] = constants.InlineQueryLimit.MAX_OFFSET_LENGTH
+    """:const:`telegram.constants.InlineQueryLimit.MAX_OFFSET_LENGTH`
+
+    .. versionadded:: 20.0
+    """
+    MAX_QUERY_LENGTH: ClassVar[int] = constants.InlineQueryLimit.MAX_QUERY_LENGTH
+    """:const:`telegram.constants.InlineQueryLimit.MAX_QUERY_LENGTH`
 
     .. versionadded:: 20.0
     """

telegram/_inline/inlinequeryresult.py

@@ -19,8 +19,9 @@
 # pylint: disable=redefined-builtin
 """This module contains the classes that represent Telegram InlineQueryResult."""
 
-from typing import Any
+from typing import ClassVar
 
+from telegram import constants
 from telegram._telegramobject import TelegramObject
 from telegram._utils.types import JSONDict
 
@@ -35,37 +36,41 @@ class InlineQueryResult(TelegramObject):
         All URLs passed in inline query results will be available to end users and therefore must
         be assumed to be *public*.
 
+    Examples:
+        :any:`Inline Bot <examples.inlinebot>`
+
     Args:
         type (:obj:`str`): Type of the result.
-        id (:obj:`str`): Unique identifier for this result, 1-64 Bytes.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
 
     Attributes:
         type (:obj:`str`): Type of the result.
-        id (:obj:`str`): Unique identifier for this result, 1-64 Bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
 
     """
 
     __slots__ = ("type", "id")
 
-    def __init__(self, type: str, id: str, **_kwargs: Any):  # pylint: disable=invalid-name
+    def __init__(self, type: str, id: str, *, api_kwargs: JSONDict = None):
+        super().__init__(api_kwargs=api_kwargs)
+
         # Required
         self.type = type
         self.id = str(id)  # pylint: disable=invalid-name
 
         self._id_attrs = (self.id,)
 
-    def to_dict(self) -> JSONDict:
-        """See :meth:`telegram.TelegramObject.to_dict`."""
-        data = super().to_dict()
+    MIN_ID_LENGTH: ClassVar[int] = constants.InlineQueryResultLimit.MIN_ID_LENGTH
+    """:const:`telegram.constants.InlineQueryResultLimit.MIN_ID_LENGTH`
 
-        # pylint: disable=no-member
-        if (
-            hasattr(self, "caption_entities")
-            and self.caption_entities  # type: ignore[attr-defined]
-        ):
-            data["caption_entities"] = [
-                ce.to_dict() for ce in self.caption_entities  # type: ignore[attr-defined]
-            ]
+    .. versionadded:: 20.0
+    """
+    MAX_ID_LENGTH: ClassVar[int] = constants.InlineQueryResultLimit.MAX_ID_LENGTH
+    """:const:`telegram.constants.InlineQueryResultLimit.MAX_ID_LENGTH`
 
-        return data
+    .. versionadded:: 20.0
+    """

telegram/_inline/inlinequeryresultarticle.py

@@ -18,10 +18,11 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InlineQueryResultArticle."""
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
+from telegram._utils.types import JSONDict
 from telegram.constants import InlineQueryResultType
 
 if TYPE_CHECKING:
@@ -31,10 +32,13 @@ if TYPE_CHECKING:
 class InlineQueryResultArticle(InlineQueryResult):
     """This object represents a Telegram InlineQueryResultArticle.
 
-    .. seealso:: `Inline Example <examples.inlinebot.html>`_
+    Examples:
+        :any:`Inline Bot <examples.inlinebot>`
 
     Args:
-        id (:obj:`str`): Unique identifier for this result, 1-64 Bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         title (:obj:`str`): Title of the result.
         input_message_content (:class:`telegram.InputMessageContent`): Content of the message to
             be sent.
@@ -47,11 +51,12 @@ class InlineQueryResultArticle(InlineQueryResult):
         thumb_url (:obj:`str`, optional): Url of the thumbnail for the result.
         thumb_width (:obj:`int`, optional): Thumbnail width.
         thumb_height (:obj:`int`, optional): Thumbnail height.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.ARTICLE`.
-        id (:obj:`str`): Unique identifier for this result, 1-64 Bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         title (:obj:`str`): Title of the result.
         input_message_content (:class:`telegram.InputMessageContent`): Content of the message to
             be sent.
@@ -91,11 +96,12 @@ class InlineQueryResultArticle(InlineQueryResult):
         thumb_url: str = None,
         thumb_width: int = None,
         thumb_height: int = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
 
         # Required
-        super().__init__(InlineQueryResultType.ARTICLE, id)
+        super().__init__(InlineQueryResultType.ARTICLE, id, api_kwargs=api_kwargs)
         self.title = title
         self.input_message_content = input_message_content
 

telegram/_inline/inlinequeryresultaudio.py

@@ -18,13 +18,13 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InlineQueryResultAudio."""
 
-from typing import TYPE_CHECKING, Any, List, Tuple, Union
+from typing import TYPE_CHECKING, List, Tuple, Union
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
 from telegram._messageentity import MessageEntity
 from telegram._utils.defaultvalue import DEFAULT_NONE
-from telegram._utils.types import ODVInput
+from telegram._utils.types import JSONDict, ODVInput
 from telegram.constants import InlineQueryResultType
 
 if TYPE_CHECKING:
@@ -38,7 +38,9 @@ class InlineQueryResultAudio(InlineQueryResult):
     content instead of the audio.
 
     Args:
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         audio_url (:obj:`str`): A valid URL for the audio file.
         title (:obj:`str`): Title.
         performer (:obj:`str`, optional): Performer.
@@ -46,21 +48,18 @@ class InlineQueryResultAudio(InlineQueryResult):
         caption (:obj:`str`, optional): Caption,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
             message to be sent instead of the audio.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.AUDIO`.
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         audio_url (:obj:`str`): A valid URL for the audio file.
         title (:obj:`str`): Title.
         performer (:obj:`str`): Optional. Performer.
@@ -68,12 +67,8 @@ class InlineQueryResultAudio(InlineQueryResult):
         caption (:obj:`str`): Optional. Caption,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`): Optional. |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -105,11 +100,12 @@ class InlineQueryResultAudio(InlineQueryResult):
         input_message_content: "InputMessageContent" = None,
         parse_mode: ODVInput[str] = DEFAULT_NONE,
         caption_entities: Union[Tuple[MessageEntity, ...], List[MessageEntity]] = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
 
         # Required
-        super().__init__(InlineQueryResultType.AUDIO, id)
+        super().__init__(InlineQueryResultType.AUDIO, id, api_kwargs=api_kwargs)
         self.audio_url = audio_url
         self.title = title
 

telegram/_inline/inlinequeryresultcachedaudio.py

@@ -18,13 +18,13 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InlineQueryResultCachedAudio."""
 
-from typing import TYPE_CHECKING, Any, List, Tuple, Union
+from typing import TYPE_CHECKING, List, Tuple, Union
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
 from telegram._messageentity import MessageEntity
 from telegram._utils.defaultvalue import DEFAULT_NONE
-from telegram._utils.types import ODVInput
+from telegram._utils.types import JSONDict, ODVInput
 from telegram.constants import InlineQueryResultType
 
 if TYPE_CHECKING:
@@ -38,36 +38,31 @@ class InlineQueryResultCachedAudio(InlineQueryResult):
     send a message with the specified content instead of the audio.
 
     Args:
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         audio_file_id (:obj:`str`): A valid file identifier for the audio file.
         caption (:obj:`str`, optional): Caption,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
             message to be sent instead of the audio.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.AUDIO`.
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         audio_file_id (:obj:`str`): A valid file identifier for the audio file.
         caption (:obj:`str`): Optional. Caption,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`, optionals): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -93,10 +88,11 @@ class InlineQueryResultCachedAudio(InlineQueryResult):
         input_message_content: "InputMessageContent" = None,
         parse_mode: ODVInput[str] = DEFAULT_NONE,
         caption_entities: Union[Tuple[MessageEntity, ...], List[MessageEntity]] = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         # Required
-        super().__init__(InlineQueryResultType.AUDIO, id)
+        super().__init__(InlineQueryResultType.AUDIO, id, api_kwargs=api_kwargs)
         self.audio_file_id = audio_file_id
 
         # Optionals

telegram/_inline/inlinequeryresultcacheddocument.py

@@ -18,13 +18,13 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InlineQueryResultCachedDocument."""
 
-from typing import TYPE_CHECKING, Any, List, Tuple, Union
+from typing import TYPE_CHECKING, List, Tuple, Union
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
 from telegram._messageentity import MessageEntity
 from telegram._utils.defaultvalue import DEFAULT_NONE
-from telegram._utils.types import ODVInput
+from telegram._utils.types import JSONDict, ODVInput
 from telegram.constants import InlineQueryResultType
 
 if TYPE_CHECKING:
@@ -38,40 +38,35 @@ class InlineQueryResultCachedDocument(InlineQueryResult):
     to send a message with the specified content instead of the file.
 
     Args:
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         title (:obj:`str`): Title for the result.
         document_file_id (:obj:`str`): A valid file identifier for the file.
         description (:obj:`str`, optional): Short description of the result.
         caption (:obj:`str`, optional): Caption of the document to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
             message to be sent instead of the file.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.DOCUMENT`.
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         title (:obj:`str`): Title for the result.
         document_file_id (:obj:`str`): A valid file identifier for the file.
         description (:obj:`str`): Optional. Short description of the result.
         caption (:obj:`str`): Optional. Caption of the document to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption.. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`): Optional. |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -101,10 +96,11 @@ class InlineQueryResultCachedDocument(InlineQueryResult):
         input_message_content: "InputMessageContent" = None,
         parse_mode: ODVInput[str] = DEFAULT_NONE,
         caption_entities: Union[Tuple[MessageEntity, ...], List[MessageEntity]] = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         # Required
-        super().__init__(InlineQueryResultType.DOCUMENT, id)
+        super().__init__(InlineQueryResultType.DOCUMENT, id, api_kwargs=api_kwargs)
         self.title = title
         self.document_file_id = document_file_id
 

telegram/_inline/inlinequeryresultcachedgif.py

@@ -18,13 +18,13 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InlineQueryResultCachedGif."""
 
-from typing import TYPE_CHECKING, Any, List, Tuple, Union
+from typing import TYPE_CHECKING, List, Tuple, Union
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
 from telegram._messageentity import MessageEntity
 from telegram._utils.defaultvalue import DEFAULT_NONE
-from telegram._utils.types import ODVInput
+from telegram._utils.types import JSONDict, ODVInput
 from telegram.constants import InlineQueryResultType
 
 if TYPE_CHECKING:
@@ -39,38 +39,33 @@ class InlineQueryResultCachedGif(InlineQueryResult):
     the animation.
 
     Args:
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         gif_file_id (:obj:`str`): A valid file identifier for the GIF file.
         title (:obj:`str`, optional): Title for the result.caption (:obj:`str`, optional):
         caption (:obj:`str`, optional): Caption of the GIF file to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
             message to be sent instead of the gif.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.GIF`.
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         gif_file_id (:obj:`str`): A valid file identifier for the GIF file.
         title (:obj:`str`): Optional. Title for the result.
         caption (:obj:`str`): Optional. Caption of the GIF file to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`): Optional. |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -98,10 +93,11 @@ class InlineQueryResultCachedGif(InlineQueryResult):
         input_message_content: "InputMessageContent" = None,
         parse_mode: ODVInput[str] = DEFAULT_NONE,
         caption_entities: Union[Tuple[MessageEntity, ...], List[MessageEntity]] = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         # Required
-        super().__init__(InlineQueryResultType.GIF, id)
+        super().__init__(InlineQueryResultType.GIF, id, api_kwargs=api_kwargs)
         self.gif_file_id = gif_file_id
 
         # Optionals

telegram/_inline/inlinequeryresultcachedmpeg4gif.py

@@ -18,13 +18,13 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InlineQueryResultMpeg4Gif."""
 
-from typing import TYPE_CHECKING, Any, List, Tuple, Union
+from typing import TYPE_CHECKING, List, Tuple, Union
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
 from telegram._messageentity import MessageEntity
 from telegram._utils.defaultvalue import DEFAULT_NONE
-from telegram._utils.types import ODVInput
+from telegram._utils.types import JSONDict, ODVInput
 from telegram.constants import InlineQueryResultType
 
 if TYPE_CHECKING:
@@ -39,38 +39,33 @@ class InlineQueryResultCachedMpeg4Gif(InlineQueryResult):
     with the specified content instead of the animation.
 
     Args:
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         mpeg4_file_id (:obj:`str`): A valid file identifier for the MP4 file.
         title (:obj:`str`, optional): Title for the result.
         caption (:obj:`str`, optional): Caption of the MPEG-4 file to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
             message to be sent instead of the MPEG-4 file.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.MPEG4GIF`.
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         mpeg4_file_id (:obj:`str`): A valid file identifier for the MP4 file.
         title (:obj:`str`): Optional. Title for the result.
         caption (:obj:`str`): Optional. Caption of the MPEG-4 file to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`): Optional. |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -98,10 +93,11 @@ class InlineQueryResultCachedMpeg4Gif(InlineQueryResult):
         input_message_content: "InputMessageContent" = None,
         parse_mode: ODVInput[str] = DEFAULT_NONE,
         caption_entities: Union[Tuple[MessageEntity, ...], List[MessageEntity]] = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         # Required
-        super().__init__(InlineQueryResultType.MPEG4GIF, id)
+        super().__init__(InlineQueryResultType.MPEG4GIF, id, api_kwargs=api_kwargs)
         self.mpeg4_file_id = mpeg4_file_id
 
         # Optionals

telegram/_inline/inlinequeryresultcachedphoto.py

@@ -18,13 +18,13 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InlineQueryResultPhoto"""
 
-from typing import TYPE_CHECKING, Any, List, Tuple, Union
+from typing import TYPE_CHECKING, List, Tuple, Union
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
 from telegram._messageentity import MessageEntity
 from telegram._utils.defaultvalue import DEFAULT_NONE
-from telegram._utils.types import ODVInput
+from telegram._utils.types import JSONDict, ODVInput
 from telegram.constants import InlineQueryResultType
 
 if TYPE_CHECKING:
@@ -39,40 +39,35 @@ class InlineQueryResultCachedPhoto(InlineQueryResult):
     of the photo.
 
     Args:
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         photo_file_id (:obj:`str`): A valid file identifier of the photo.
         title (:obj:`str`, optional): Title for the result.
         description (:obj:`str`, optional): Short description of the result.
         caption (:obj:`str`, optional): Caption of the photo to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
             message to be sent instead of the photo.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.PHOTO`.
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         photo_file_id (:obj:`str`): A valid file identifier of the photo.
         title (:obj:`str`): Optional. Title for the result.
         description (:obj:`str`): Optional. Short description of the result.
         caption (:obj:`str`): Optional. Caption of the photo to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`): Optional. |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -102,10 +97,11 @@ class InlineQueryResultCachedPhoto(InlineQueryResult):
         input_message_content: "InputMessageContent" = None,
         parse_mode: ODVInput[str] = DEFAULT_NONE,
         caption_entities: Union[Tuple[MessageEntity, ...], List[MessageEntity]] = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         # Required
-        super().__init__(InlineQueryResultType.PHOTO, id)
+        super().__init__(InlineQueryResultType.PHOTO, id, api_kwargs=api_kwargs)
         self.photo_file_id = photo_file_id
 
         # Optionals

telegram/_inline/inlinequeryresultcachedsticker.py

@@ -18,10 +18,11 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InlineQueryResultCachedSticker."""
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
+from telegram._utils.types import JSONDict
 from telegram.constants import InlineQueryResultType
 
 if TYPE_CHECKING:
@@ -35,17 +36,20 @@ class InlineQueryResultCachedSticker(InlineQueryResult):
     message with the specified content instead of the sticker.
 
     Args:
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         sticker_file_id (:obj:`str`): A valid file identifier of the sticker.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
             message to be sent instead of the sticker.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.STICKER`.
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         sticker_file_id (:obj:`str`): A valid file identifier of the sticker.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
@@ -62,10 +66,11 @@ class InlineQueryResultCachedSticker(InlineQueryResult):
         sticker_file_id: str,
         reply_markup: InlineKeyboardMarkup = None,
         input_message_content: "InputMessageContent" = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         # Required
-        super().__init__(InlineQueryResultType.STICKER, id)
+        super().__init__(InlineQueryResultType.STICKER, id, api_kwargs=api_kwargs)
         self.sticker_file_id = sticker_file_id
 
         # Optionals

telegram/_inline/inlinequeryresultcachedvideo.py

@@ -18,13 +18,13 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InlineQueryResultCachedVideo."""
 
-from typing import TYPE_CHECKING, Any, List, Tuple, Union
+from typing import TYPE_CHECKING, List, Tuple, Union
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
 from telegram._messageentity import MessageEntity
 from telegram._utils.defaultvalue import DEFAULT_NONE
-from telegram._utils.types import ODVInput
+from telegram._utils.types import JSONDict, ODVInput
 from telegram.constants import InlineQueryResultType
 
 if TYPE_CHECKING:
@@ -39,40 +39,35 @@ class InlineQueryResultCachedVideo(InlineQueryResult):
     of the video.
 
     Args:
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         video_file_id (:obj:`str`): A valid file identifier for the video file.
         title (:obj:`str`): Title for the result.
         description (:obj:`str`, optional): Short description of the result.
         caption (:obj:`str`, optional): Caption of the video to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
             message to be sent instead of the video.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.VIDEO`.
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         video_file_id (:obj:`str`): A valid file identifier for the video file.
         title (:obj:`str`): Title for the result.
         description (:obj:`str`): Optional. Short description of the result.
         caption (:obj:`str`): Optional. Caption of the video to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`): Optional. |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -102,10 +97,11 @@ class InlineQueryResultCachedVideo(InlineQueryResult):
         input_message_content: "InputMessageContent" = None,
         parse_mode: ODVInput[str] = DEFAULT_NONE,
         caption_entities: Union[Tuple[MessageEntity, ...], List[MessageEntity]] = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         # Required
-        super().__init__(InlineQueryResultType.VIDEO, id)
+        super().__init__(InlineQueryResultType.VIDEO, id, api_kwargs=api_kwargs)
         self.video_file_id = video_file_id
         self.title = title
 

telegram/_inline/inlinequeryresultcachedvoice.py

@@ -18,13 +18,13 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InlineQueryResultCachedVoice."""
 
-from typing import TYPE_CHECKING, Any, List, Tuple, Union
+from typing import TYPE_CHECKING, List, Tuple, Union
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
 from telegram._messageentity import MessageEntity
 from telegram._utils.defaultvalue import DEFAULT_NONE
-from telegram._utils.types import ODVInput
+from telegram._utils.types import JSONDict, ODVInput
 from telegram.constants import InlineQueryResultType
 
 if TYPE_CHECKING:
@@ -38,38 +38,33 @@ class InlineQueryResultCachedVoice(InlineQueryResult):
     send a message with the specified content instead of the voice message.
 
     Args:
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         voice_file_id (:obj:`str`): A valid file identifier for the voice message.
         title (:obj:`str`): Voice message title.
         caption (:obj:`str`, optional): Caption,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
             message to be sent instead of the voice message.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.VOICE`.
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         voice_file_id (:obj:`str`): A valid file identifier for the voice message.
         title (:obj:`str`): Voice message title.
         caption (:obj:`str`): Optional. Caption,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`): Optional. |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -97,10 +92,11 @@ class InlineQueryResultCachedVoice(InlineQueryResult):
         input_message_content: "InputMessageContent" = None,
         parse_mode: ODVInput[str] = DEFAULT_NONE,
         caption_entities: Union[Tuple[MessageEntity, ...], List[MessageEntity]] = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         # Required
-        super().__init__(InlineQueryResultType.VOICE, id)
+        super().__init__(InlineQueryResultType.VOICE, id, api_kwargs=api_kwargs)
         self.voice_file_id = voice_file_id
         self.title = title
 

telegram/_inline/inlinequeryresultcontact.py

@@ -18,10 +18,11 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InlineQueryResultContact."""
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
+from telegram._utils.types import JSONDict
 from telegram.constants import InlineQueryResultType
 
 if TYPE_CHECKING:
@@ -35,12 +36,14 @@ class InlineQueryResultContact(InlineQueryResult):
     content instead of the contact.
 
     Args:
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         phone_number (:obj:`str`): Contact's phone number.
         first_name (:obj:`str`): Contact's first name.
         last_name (:obj:`str`, optional): Contact's last name.
         vcard (:obj:`str`, optional): Additional data about the contact in the form of a vCard,
-            0-2048 bytes.
+            0-:tg-const:`telegram.constants.ContactLimit.VCARD` bytes.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -48,16 +51,17 @@ class InlineQueryResultContact(InlineQueryResult):
         thumb_url (:obj:`str`, optional): Url of the thumbnail for the result.
         thumb_width (:obj:`int`, optional): Thumbnail width.
         thumb_height (:obj:`int`, optional): Thumbnail height.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.CONTACT`.
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         phone_number (:obj:`str`): Contact's phone number.
         first_name (:obj:`str`): Contact's first name.
         last_name (:obj:`str`): Optional. Contact's last name.
         vcard (:obj:`str`): Optional. Additional data about the contact in the form of a vCard,
-            0-2048 bytes.
+            0-:tg-const:`telegram.constants.ContactLimit.VCARD` bytes.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -92,10 +96,11 @@ class InlineQueryResultContact(InlineQueryResult):
         thumb_width: int = None,
         thumb_height: int = None,
         vcard: str = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         # Required
-        super().__init__(InlineQueryResultType.CONTACT, id)
+        super().__init__(InlineQueryResultType.CONTACT, id, api_kwargs=api_kwargs)
         self.phone_number = phone_number
         self.first_name = first_name
 

telegram/_inline/inlinequeryresultdocument.py

@@ -18,13 +18,13 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InlineQueryResultDocument"""
 
-from typing import TYPE_CHECKING, Any, List, Tuple, Union
+from typing import TYPE_CHECKING, List, Tuple, Union
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
 from telegram._messageentity import MessageEntity
 from telegram._utils.defaultvalue import DEFAULT_NONE
-from telegram._utils.types import ODVInput
+from telegram._utils.types import JSONDict, ODVInput
 from telegram.constants import InlineQueryResultType
 
 if TYPE_CHECKING:
@@ -39,17 +39,15 @@ class InlineQueryResultDocument(InlineQueryResult):
     using this method.
 
     Args:
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         title (:obj:`str`): Title for the result.
         caption (:obj:`str`, optional): Caption of the document to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
         document_url (:obj:`str`): A valid URL for the file.
         mime_type (:obj:`str`): Mime type of the content of the file, either "application/pdf"
             or "application/zip".
@@ -61,21 +59,18 @@ class InlineQueryResultDocument(InlineQueryResult):
         thumb_url (:obj:`str`, optional): URL of the thumbnail (JPEG only) for the file.
         thumb_width (:obj:`int`, optional): Thumbnail width.
         thumb_height (:obj:`int`, optional): Thumbnail height.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.DOCUMENT`.
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         title (:obj:`str`): Title for the result.
         caption (:obj:`str`): Optional. Caption of the document to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`): Optional. |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
         document_url (:obj:`str`): A valid URL for the file.
         mime_type (:obj:`str`): Mime type of the content of the file, either "application/pdf"
             or "application/zip".
@@ -120,10 +115,11 @@ class InlineQueryResultDocument(InlineQueryResult):
         thumb_height: int = None,
         parse_mode: ODVInput[str] = DEFAULT_NONE,
         caption_entities: Union[Tuple[MessageEntity, ...], List[MessageEntity]] = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         # Required
-        super().__init__(InlineQueryResultType.DOCUMENT, id)
+        super().__init__(InlineQueryResultType.DOCUMENT, id, api_kwargs=api_kwargs)
         self.document_url = document_url
         self.title = title
         self.mime_type = mime_type

telegram/_inline/inlinequeryresultgame.py

@@ -18,10 +18,9 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InlineQueryResultGame."""
 
-from typing import Any
-
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
+from telegram._utils.types import JSONDict
 from telegram.constants import InlineQueryResultType
 
 
@@ -29,15 +28,18 @@ class InlineQueryResultGame(InlineQueryResult):
     """Represents a :class:`telegram.Game`.
 
     Args:
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         game_short_name (:obj:`str`): Short name of the game.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.GAME`.
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         game_short_name (:obj:`str`): Short name of the game.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
@@ -51,10 +53,11 @@ class InlineQueryResultGame(InlineQueryResult):
         id: str,  # pylint: disable=redefined-builtin
         game_short_name: str,
         reply_markup: InlineKeyboardMarkup = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         # Required
-        super().__init__(InlineQueryResultType.GAME, id)
+        super().__init__(InlineQueryResultType.GAME, id, api_kwargs=api_kwargs)
         self.id = id
         self.game_short_name = game_short_name
 

telegram/_inline/inlinequeryresultgif.py

@@ -18,13 +18,13 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InlineQueryResultGif."""
 
-from typing import TYPE_CHECKING, Any, List, Tuple, Union
+from typing import TYPE_CHECKING, List, Tuple, Union
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
 from telegram._messageentity import MessageEntity
 from telegram._utils.defaultvalue import DEFAULT_NONE
-from telegram._utils.types import ODVInput
+from telegram._utils.types import JSONDict, ODVInput
 from telegram.constants import InlineQueryResultType
 
 if TYPE_CHECKING:
@@ -38,7 +38,9 @@ class InlineQueryResultGif(InlineQueryResult):
     send a message with the specified content instead of the animation.
 
     Args:
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         gif_url (:obj:`str`): A valid URL for the GIF file. File size must not exceed 1MB.
         gif_width (:obj:`int`, optional): Width of the GIF.
         gif_height (:obj:`int`, optional): Height of the GIF.
@@ -51,21 +53,18 @@ class InlineQueryResultGif(InlineQueryResult):
         caption (:obj:`str`, optional): Caption of the GIF file to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
             message to be sent instead of the GIF animation.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.GIF`.
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         gif_url (:obj:`str`): A valid URL for the GIF file. File size must not exceed 1MB.
         gif_width (:obj:`int`): Optional. Width of the GIF.
         gif_height (:obj:`int`): Optional. Height of the GIF.
@@ -77,12 +76,8 @@ class InlineQueryResultGif(InlineQueryResult):
         caption (:obj:`str`): Optional. Caption of the GIF file to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`): Optional. |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -120,11 +115,12 @@ class InlineQueryResultGif(InlineQueryResult):
         parse_mode: ODVInput[str] = DEFAULT_NONE,
         thumb_mime_type: str = None,
         caption_entities: Union[Tuple[MessageEntity, ...], List[MessageEntity]] = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
 
         # Required
-        super().__init__(InlineQueryResultType.GIF, id)
+        super().__init__(InlineQueryResultType.GIF, id, api_kwargs=api_kwargs)
         self.gif_url = gif_url
         self.thumb_url = thumb_url
 

telegram/_inline/inlinequeryresultlocation.py

@@ -18,11 +18,12 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InlineQueryResultLocation."""
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, ClassVar
 
+from telegram import constants
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
-from telegram.constants import InlineQueryResultType
+from telegram._utils.types import JSONDict
 
 if TYPE_CHECKING:
     from telegram import InputMessageContent
@@ -35,20 +36,28 @@ class InlineQueryResultLocation(InlineQueryResult):
     content instead of the location.
 
     Args:
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         latitude (:obj:`float`): Location latitude in degrees.
         longitude (:obj:`float`): Location longitude in degrees.
         title (:obj:`str`): Location title.
         horizontal_accuracy (:obj:`float`, optional): The radius of uncertainty for the location,
-            measured in meters; 0-:tg-const:`telegram.constants.LocationLimit.HORIZONTAL_ACCURACY`.
-        live_period (:obj:`int`, optional): Period in seconds for which the location can be
-            updated, should be between 60 and 86400.
+            measured in meters; 0-
+            :tg-const:`telegram.InlineQueryResultLocation.HORIZONTAL_ACCURACY`.
+        live_period (:obj:`int`, optional): Period in seconds for which the location will be
+            updated, should be between
+            :tg-const:`telegram.InlineQueryResultLocation.MIN_LIVE_PERIOD` and
+            :tg-const:`telegram.InlineQueryResultLocation.MAX_LIVE_PERIOD`.
         heading (:obj:`int`, optional): For live locations, a direction in which the user is
-            moving, in degrees. Must be between 1 and
-            :tg-const:`telegram.constants.LocationLimit.HEADING` if specified.
-        proximity_alert_radius (:obj:`int`, optional): For live locations, a maximum distance for
-            proximity alerts about approaching another chat member, in meters. Must be between 1
-            and :tg-const:`telegram.constants.LocationLimit.HEADING` if specified.
+            moving, in degrees. Must be between
+            :tg-const:`telegram.InlineQueryResultLocation.MIN_HEADING` and
+            :tg-const:`telegram.InlineQueryResultLocation.MAX_HEADING` if specified.
+        proximity_alert_radius (:obj:`int`, optional): For live locations, a maximum distance
+            for proximity alerts about approaching another chat member, in meters. Must be
+            between :tg-const:`telegram.InlineQueryResultLocation.MIN_PROXIMITY_ALERT_RADIUS`
+            and :tg-const:`telegram.InlineQueryResultLocation.MAX_PROXIMITY_ALERT_RADIUS`
+            if specified.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
@@ -56,11 +65,12 @@ class InlineQueryResultLocation(InlineQueryResult):
         thumb_url (:obj:`str`, optional): Url of the thumbnail for the result.
         thumb_width (:obj:`int`, optional): Thumbnail width.
         thumb_height (:obj:`int`, optional): Thumbnail height.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.LOCATION`.
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         latitude (:obj:`float`): Location latitude in degrees.
         longitude (:obj:`float`): Location longitude in degrees.
         title (:obj:`str`): Location title.
@@ -112,10 +122,11 @@ class InlineQueryResultLocation(InlineQueryResult):
         horizontal_accuracy: float = None,
         heading: int = None,
         proximity_alert_radius: int = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         # Required
-        super().__init__(InlineQueryResultType.LOCATION, id)
+        super().__init__(constants.InlineQueryResultType.LOCATION, id, api_kwargs=api_kwargs)
         self.latitude = latitude
         self.longitude = longitude
         self.title = title
@@ -132,3 +143,39 @@ class InlineQueryResultLocation(InlineQueryResult):
         self.proximity_alert_radius = (
             int(proximity_alert_radius) if proximity_alert_radius else None
         )
+
+    HORIZONTAL_ACCURACY: ClassVar[int] = constants.LocationLimit.HORIZONTAL_ACCURACY
+    """:const:`telegram.constants.LocationLimit.HORIZONTAL_ACCURACY`
+
+    .. versionadded:: 20.0
+    """
+    MIN_HEADING: ClassVar[int] = constants.LocationLimit.MIN_HEADING
+    """:const:`telegram.constants.LocationLimit.MIN_HEADING`
+
+    .. versionadded:: 20.0
+    """
+    MAX_HEADING: ClassVar[int] = constants.LocationLimit.MAX_HEADING
+    """:const:`telegram.constants.LocationLimit.MAX_HEADING`
+
+    .. versionadded:: 20.0
+    """
+    MIN_LIVE_PERIOD: ClassVar[int] = constants.LocationLimit.MIN_LIVE_PERIOD
+    """:const:`telegram.constants.LocationLimit.MIN_LIVE_PERIOD`
+
+    .. versionadded:: 20.0
+    """
+    MAX_LIVE_PERIOD: ClassVar[int] = constants.LocationLimit.MAX_LIVE_PERIOD
+    """:const:`telegram.constants.LocationLimit.MAX_LIVE_PERIOD`
+
+    .. versionadded:: 20.0
+    """
+    MIN_PROXIMITY_ALERT_RADIUS: ClassVar[int] = constants.LocationLimit.MIN_PROXIMITY_ALERT_RADIUS
+    """:const:`telegram.constants.LocationLimit.MIN_PROXIMITY_ALERT_RADIUS`
+
+    .. versionadded:: 20.0
+    """
+    MAX_PROXIMITY_ALERT_RADIUS: ClassVar[int] = constants.LocationLimit.MAX_PROXIMITY_ALERT_RADIUS
+    """:const:`telegram.constants.LocationLimit.MAX_PROXIMITY_ALERT_RADIUS`
+
+    .. versionadded:: 20.0
+    """

telegram/_inline/inlinequeryresultmpeg4gif.py

@@ -18,13 +18,13 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InlineQueryResultMpeg4Gif."""
 
-from typing import TYPE_CHECKING, Any, List, Tuple, Union
+from typing import TYPE_CHECKING, List, Tuple, Union
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
 from telegram._messageentity import MessageEntity
 from telegram._utils.defaultvalue import DEFAULT_NONE
-from telegram._utils.types import ODVInput
+from telegram._utils.types import JSONDict, ODVInput
 from telegram.constants import InlineQueryResultType
 
 if TYPE_CHECKING:
@@ -39,7 +39,9 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult):
     animation.
 
     Args:
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         mpeg4_url (:obj:`str`): A valid URL for the MP4 file. File size must not exceed 1MB.
         mpeg4_width (:obj:`int`, optional): Video width.
         mpeg4_height (:obj:`int`, optional): Video height.
@@ -51,21 +53,18 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult):
         caption (:obj:`str`, optional): Caption of the MPEG-4 file to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
             message to be sent instead of the video animation.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.MPEG4GIF`.
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         mpeg4_url (:obj:`str`): A valid URL for the MP4 file. File size must not exceed 1MB.
         mpeg4_width (:obj:`int`): Optional. Video width.
         mpeg4_height (:obj:`int`): Optional. Video height.
@@ -77,12 +76,8 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult):
         caption (:obj:`str`): Optional. Caption of the MPEG-4 file to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters
             after entities parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`): Optional. |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -120,11 +115,12 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult):
         parse_mode: ODVInput[str] = DEFAULT_NONE,
         thumb_mime_type: str = None,
         caption_entities: Union[Tuple[MessageEntity, ...], List[MessageEntity]] = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
 
         # Required
-        super().__init__(InlineQueryResultType.MPEG4GIF, id)
+        super().__init__(InlineQueryResultType.MPEG4GIF, id, api_kwargs=api_kwargs)
         self.mpeg4_url = mpeg4_url
         self.thumb_url = thumb_url
 

telegram/_inline/inlinequeryresultphoto.py

@@ -18,13 +18,13 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InlineQueryResultPhoto."""
 
-from typing import TYPE_CHECKING, Any, List, Tuple, Union
+from typing import TYPE_CHECKING, List, Tuple, Union
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
 from telegram._messageentity import MessageEntity
 from telegram._utils.defaultvalue import DEFAULT_NONE
-from telegram._utils.types import ODVInput
+from telegram._utils.types import JSONDict, ODVInput
 from telegram.constants import InlineQueryResultType
 
 if TYPE_CHECKING:
@@ -38,7 +38,9 @@ class InlineQueryResultPhoto(InlineQueryResult):
     specified content instead of the photo.
 
     Args:
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         photo_url (:obj:`str`): A valid URL of the photo. Photo must be in JPEG format. Photo size
             must not exceed 5MB.
         thumb_url (:obj:`str`): URL of the thumbnail for the photo.
@@ -49,21 +51,18 @@ class InlineQueryResultPhoto(InlineQueryResult):
         caption (:obj:`str`, optional): Caption of the photo to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
             message to be sent instead of the photo.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.PHOTO`.
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         photo_url (:obj:`str`): A valid URL of the photo. Photo must be in JPEG format. Photo size
             must not exceed 5MB.
         thumb_url (:obj:`str`): URL of the thumbnail for the photo.
@@ -74,12 +73,8 @@ class InlineQueryResultPhoto(InlineQueryResult):
         caption (:obj:`str`): Optional. Caption of the photo to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`): Optional. |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
@@ -115,10 +110,11 @@ class InlineQueryResultPhoto(InlineQueryResult):
         input_message_content: "InputMessageContent" = None,
         parse_mode: ODVInput[str] = DEFAULT_NONE,
         caption_entities: Union[Tuple[MessageEntity, ...], List[MessageEntity]] = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
         # Required
-        super().__init__(InlineQueryResultType.PHOTO, id)
+        super().__init__(InlineQueryResultType.PHOTO, id, api_kwargs=api_kwargs)
         self.photo_url = photo_url
         self.thumb_url = thumb_url
 

telegram/_inline/inlinequeryresultvenue.py

@@ -18,10 +18,11 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InlineQueryResultVenue."""
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
+from telegram._utils.types import JSONDict
 from telegram.constants import InlineQueryResultType
 
 if TYPE_CHECKING:
@@ -39,7 +40,9 @@ class InlineQueryResultVenue(InlineQueryResult):
       behaviour is undocumented and might be changed by Telegram.
 
     Args:
-        id (:obj:`str`): Unique identifier for this result, 1-64 Bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         latitude (:obj:`float`): Latitude of the venue location in degrees.
         longitude (:obj:`float`): Longitude of the venue location in degrees.
         title (:obj:`str`): Title of the venue.
@@ -59,11 +62,12 @@ class InlineQueryResultVenue(InlineQueryResult):
         thumb_url (:obj:`str`, optional): Url of the thumbnail for the result.
         thumb_width (:obj:`int`, optional): Thumbnail width.
         thumb_height (:obj:`int`, optional): Thumbnail height.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.VENUE`.
-        id (:obj:`str`): Unique identifier for this result, 1-64 Bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         latitude (:obj:`float`): Latitude of the venue location in degrees.
         longitude (:obj:`float`): Longitude of the venue location in degrees.
         title (:obj:`str`): Title of the venue.
@@ -114,11 +118,12 @@ class InlineQueryResultVenue(InlineQueryResult):
         thumb_height: int = None,
         google_place_id: str = None,
         google_place_type: str = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
 
         # Required
-        super().__init__(InlineQueryResultType.VENUE, id)
+        super().__init__(InlineQueryResultType.VENUE, id, api_kwargs=api_kwargs)
         self.latitude = latitude
         self.longitude = longitude
         self.title = title

telegram/_inline/inlinequeryresultvideo.py

@@ -18,13 +18,13 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InlineQueryResultVideo."""
 
-from typing import TYPE_CHECKING, Any, List, Tuple, Union
+from typing import TYPE_CHECKING, List, Tuple, Union
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
 from telegram._messageentity import MessageEntity
 from telegram._utils.defaultvalue import DEFAULT_NONE
-from telegram._utils.types import ODVInput
+from telegram._utils.types import JSONDict, ODVInput
 from telegram.constants import InlineQueryResultType
 
 if TYPE_CHECKING:
@@ -43,7 +43,9 @@ class InlineQueryResultVideo(InlineQueryResult):
         replace its content using :attr:`input_message_content`.
 
     Args:
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         video_url (:obj:`str`): A valid URL for the embedded video player or video file.
         mime_type (:obj:`str`): Mime type of the content of video url, "text/html" or "video/mp4".
         thumb_url (:obj:`str`): URL of the thumbnail (JPEG only) for the video.
@@ -51,12 +53,8 @@ class InlineQueryResultVideo(InlineQueryResult):
         caption (:obj:`str`, optional): Caption,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
         video_width (:obj:`int`, optional): Video width.
         video_height (:obj:`int`, optional): Video height.
         video_duration (:obj:`int`, optional): Video duration in seconds.
@@ -67,31 +65,28 @@ class InlineQueryResultVideo(InlineQueryResult):
             message to be sent instead of the video. This field is required if
             InlineQueryResultVideo is used to send an HTML-page as a result
             (e.g., a YouTube video).
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.VIDEO`.
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         video_url (:obj:`str`): A valid URL for the embedded video player or video file.
         mime_type (:obj:`str`): Mime type of the content of video url, "text/html" or "video/mp4".
         thumb_url (:obj:`str`): URL of the thumbnail (JPEG only) for the video.
         title (:obj:`str`): Title for the result.
-        caption (:obj:`str`): Optional. Caption of the video to be sent,
+        caption (:obj:`str`, optional): Caption of the video to be sent,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after
             entities parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
-        video_width (:obj:`int`): Optional. Video width.
-        video_height (:obj:`int`): Optional. Video height.
-        video_duration (:obj:`int`): Optional. Video duration in seconds.
-        description (:obj:`str`): Optional. Short description of the result.
-        reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
+        video_width (:obj:`int`, optional): Video width.
+        video_height (:obj:`int`, optional): Video height.
+        video_duration (:obj:`int`, optional): Video duration in seconds.
+        description (:obj:`str`, optional): Short description of the result.
+        reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
-        input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
+        input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
             message to be sent instead of the video. This field is required if
             InlineQueryResultVideo is used to send an HTML-page as a result
             (e.g., a YouTube video).
@@ -130,11 +125,12 @@ class InlineQueryResultVideo(InlineQueryResult):
         input_message_content: "InputMessageContent" = None,
         parse_mode: ODVInput[str] = DEFAULT_NONE,
         caption_entities: Union[Tuple[MessageEntity, ...], List[MessageEntity]] = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
 
         # Required
-        super().__init__(InlineQueryResultType.VIDEO, id)
+        super().__init__(InlineQueryResultType.VIDEO, id, api_kwargs=api_kwargs)
         self.video_url = video_url
         self.mime_type = mime_type
         self.thumb_url = thumb_url

telegram/_inline/inlinequeryresultvoice.py

@@ -18,13 +18,13 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InlineQueryResultVoice."""
 
-from typing import TYPE_CHECKING, Any, List, Tuple, Union
+from typing import TYPE_CHECKING, List, Tuple, Union
 
 from telegram._inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from telegram._inline.inlinequeryresult import InlineQueryResult
 from telegram._messageentity import MessageEntity
 from telegram._utils.defaultvalue import DEFAULT_NONE
-from telegram._utils.types import ODVInput
+from telegram._utils.types import JSONDict, ODVInput
 from telegram.constants import InlineQueryResultType
 
 if TYPE_CHECKING:
@@ -35,43 +35,38 @@ class InlineQueryResultVoice(InlineQueryResult):
     """
     Represents a link to a voice recording in an .ogg container encoded with OPUS. By default,
     this voice recording will be sent by the user. Alternatively, you can use
-    :attr:`input_message_content` to send a message with the specified content instead of the
+    :attr:`input_message_content` to send a message with the specified content instead of
     the voice message.
 
     Args:
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         voice_url (:obj:`str`): A valid URL for the voice recording.
         title (:obj:`str`): Recording title.
         caption (:obj:`str`, optional): Caption,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
         voice_duration (:obj:`int`, optional): Recording duration in seconds.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
             message to be sent instead of the voice recording.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         type (:obj:`str`): :tg-const:`telegram.constants.InlineQueryResultType.VOICE`.
-        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        id (:obj:`str`): Unique identifier for this result,
+            :tg-const:`telegram.InlineQueryResult.MIN_ID_LENGTH`-
+            :tg-const:`telegram.InlineQueryResult.MAX_ID_LENGTH` Bytes.
         voice_url (:obj:`str`): A valid URL for the voice recording.
         title (:obj:`str`): Recording title.
         caption (:obj:`str`): Optional. Caption,
             0-:tg-const:`telegram.constants.MessageLimit.CAPTION_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`): Optional. |parse_mode|
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
         voice_duration (:obj:`int`): Optional. Recording duration in seconds.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
@@ -102,11 +97,12 @@ class InlineQueryResultVoice(InlineQueryResult):
         input_message_content: "InputMessageContent" = None,
         parse_mode: ODVInput[str] = DEFAULT_NONE,
         caption_entities: Union[Tuple[MessageEntity, ...], List[MessageEntity]] = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
 
         # Required
-        super().__init__(InlineQueryResultType.VOICE, id)
+        super().__init__(InlineQueryResultType.VOICE, id, api_kwargs=api_kwargs)
         self.voice_url = voice_url
         self.title = title
 

telegram/_inline/inputcontactmessagecontent.py

@@ -18,9 +18,8 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InputContactMessageContent."""
 
-from typing import Any
-
 from telegram._inline.inputmessagecontent import InputMessageContent
+from telegram._utils.types import JSONDict
 
 
 class InputContactMessageContent(InputMessageContent):
@@ -34,15 +33,14 @@ class InputContactMessageContent(InputMessageContent):
         first_name (:obj:`str`): Contact's first name.
         last_name (:obj:`str`, optional): Contact's last name.
         vcard (:obj:`str`, optional): Additional data about the contact in the form of a vCard,
-            0-2048 bytes.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+            0-:tg-const:`telegram.constants.ContactLimit.VCARD` bytes.
 
     Attributes:
         phone_number (:obj:`str`): Contact's phone number.
         first_name (:obj:`str`): Contact's first name.
         last_name (:obj:`str`): Optional. Contact's last name.
         vcard (:obj:`str`): Optional. Additional data about the contact in the form of a vCard,
-            0-2048 bytes.
+            0-:tg-const:`telegram.constants.ContactLimit.VCARD` bytes.
 
     """
 
@@ -54,8 +52,11 @@ class InputContactMessageContent(InputMessageContent):
         first_name: str,
         last_name: str = None,
         vcard: str = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
+
         # Required
         self.phone_number = phone_number
         self.first_name = first_name

telegram/_inline/inputinvoicemessagecontent.py

@@ -18,7 +18,7 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains a class that represents a Telegram InputInvoiceMessageContent."""
 
-from typing import TYPE_CHECKING, Any, List, Optional
+from typing import TYPE_CHECKING, List, Optional
 
 from telegram._inline.inputmessagecontent import InputMessageContent
 from telegram._payment.labeledprice import LabeledPrice
@@ -89,7 +89,6 @@ class InputInvoiceMessageContent(InputMessageContent):
             should be sent to provider.
         is_flexible (:obj:`bool`, optional): Pass :obj:`True`, if the final price depends on the
             shipping method.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         title (:obj:`str`): Product name. :tg-const:`telegram.Invoice.MIN_TITLE_LENGTH`-
@@ -179,8 +178,10 @@ class InputInvoiceMessageContent(InputMessageContent):
         send_phone_number_to_provider: bool = None,
         send_email_to_provider: bool = None,
         is_flexible: bool = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
         # Required
         self.title = title
         self.description = description
@@ -227,14 +228,6 @@ class InputInvoiceMessageContent(InputMessageContent):
             )
         )
 
-    def to_dict(self) -> JSONDict:
-        """See :meth:`telegram.TelegramObject.to_dict`."""
-        data = super().to_dict()
-
-        data["prices"] = [price.to_dict() for price in self.prices]
-
-        return data
-
     @classmethod
     def de_json(
         cls, data: Optional[JSONDict], bot: "Bot"
@@ -247,4 +240,4 @@ class InputInvoiceMessageContent(InputMessageContent):
 
         data["prices"] = LabeledPrice.de_list(data.get("prices"), bot)
 
-        return cls(**data, bot=bot)
+        return super().de_json(data=data, bot=bot)

telegram/_inline/inputlocationmessagecontent.py

@@ -18,9 +18,11 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InputLocationMessageContent."""
 
-from typing import Any
+from typing import ClassVar
 
+from telegram import constants
 from telegram._inline.inputmessagecontent import InputMessageContent
+from telegram._utils.types import JSONDict
 
 
 class InputLocationMessageContent(InputMessageContent):
@@ -35,16 +37,21 @@ class InputLocationMessageContent(InputMessageContent):
         latitude (:obj:`float`): Latitude of the location in degrees.
         longitude (:obj:`float`): Longitude of the location in degrees.
         horizontal_accuracy (:obj:`float`, optional): The radius of uncertainty for the location,
-            measured in meters; 0-:tg-const:`telegram.constants.LocationLimit.HORIZONTAL_ACCURACY`.
-        live_period	(:obj:`int`, optional): Period in seconds for which the location can be
-            updated, should be between 60 and 86400.
+            measured in meters; 0-
+            :tg-const:`telegram.InputLocationMessageContent.HORIZONTAL_ACCURACY`.
+        live_period (:obj:`int`, optional): Period in seconds for which the location will be
+            updated, should be between
+            :tg-const:`telegram.InputLocationMessageContent.MIN_LIVE_PERIOD` and
+            :tg-const:`telegram.InputLocationMessageContent.MAX_LIVE_PERIOD`.
         heading (:obj:`int`, optional): For live locations, a direction in which the user is
-            moving, in degrees. Must be between 1 and
-            :tg-const:`telegram.constants.LocationLimit.HEADING` if specified.
-        proximity_alert_radius (:obj:`int`, optional): For live locations, a maximum distance for
-            proximity alerts about approaching another chat member, in meters. Must be between 1
-            and :tg-const:`telegram.constants.LocationLimit.HEADING` if specified.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+            moving, in degrees. Must be between
+            :tg-const:`telegram.InputLocationMessageContent.MIN_HEADING` and
+            :tg-const:`telegram.InputLocationMessageContent.MAX_HEADING` if specified.
+        proximity_alert_radius (:obj:`int`, optional): For live locations, a maximum distance
+            for proximity alerts about approaching another chat member, in meters. Must be
+            between :tg-const:`telegram.InputLocationMessageContent.MIN_PROXIMITY_ALERT_RADIUS`
+            and :tg-const:`telegram.InputLocationMessageContent.MAX_PROXIMITY_ALERT_RADIUS`
+            if specified.
 
     Attributes:
         latitude (:obj:`float`): Latitude of the location in degrees.
@@ -72,8 +79,10 @@ class InputLocationMessageContent(InputMessageContent):
         horizontal_accuracy: float = None,
         heading: int = None,
         proximity_alert_radius: int = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
         # Required
         self.latitude = latitude
         self.longitude = longitude
@@ -87,3 +96,39 @@ class InputLocationMessageContent(InputMessageContent):
         )
 
         self._id_attrs = (self.latitude, self.longitude)
+
+    HORIZONTAL_ACCURACY: ClassVar[int] = constants.LocationLimit.HORIZONTAL_ACCURACY
+    """:const:`telegram.constants.LocationLimit.HORIZONTAL_ACCURACY`
+
+    .. versionadded:: 20.0
+    """
+    MIN_HEADING: ClassVar[int] = constants.LocationLimit.MIN_HEADING
+    """:const:`telegram.constants.LocationLimit.MIN_HEADING`
+
+    .. versionadded:: 20.0
+    """
+    MAX_HEADING: ClassVar[int] = constants.LocationLimit.MAX_HEADING
+    """:const:`telegram.constants.LocationLimit.MAX_HEADING`
+
+    .. versionadded:: 20.0
+    """
+    MIN_LIVE_PERIOD: ClassVar[int] = constants.LocationLimit.MIN_LIVE_PERIOD
+    """:const:`telegram.constants.LocationLimit.MIN_LIVE_PERIOD`
+
+    .. versionadded:: 20.0
+    """
+    MAX_LIVE_PERIOD: ClassVar[int] = constants.LocationLimit.MAX_LIVE_PERIOD
+    """:const:`telegram.constants.LocationLimit.MAX_LIVE_PERIOD`
+
+    .. versionadded:: 20.0
+    """
+    MIN_PROXIMITY_ALERT_RADIUS: ClassVar[int] = constants.LocationLimit.MIN_PROXIMITY_ALERT_RADIUS
+    """:const:`telegram.constants.LocationLimit.MIN_PROXIMITY_ALERT_RADIUS`
+
+    .. versionadded:: 20.0
+    """
+    MAX_PROXIMITY_ALERT_RADIUS: ClassVar[int] = constants.LocationLimit.MAX_PROXIMITY_ALERT_RADIUS
+    """:const:`telegram.constants.LocationLimit.MAX_PROXIMITY_ALERT_RADIUS`
+
+    .. versionadded:: 20.0
+    """

telegram/_inline/inputtextmessagecontent.py

@@ -18,7 +18,7 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes that represent Telegram InputTextMessageContent."""
 
-from typing import Any, List, Tuple, Union
+from typing import List, Tuple, Union
 
 from telegram._inline.inputmessagecontent import InputMessageContent
 from telegram._messageentity import MessageEntity
@@ -33,32 +33,25 @@ class InputTextMessageContent(InputMessageContent):
     Objects of this class are comparable in terms of equality. Two objects of this class are
     considered equal, if their :attr:`message_text` is equal.
 
-    .. seealso:: `Inline Example <examples.inlinebot.html>`_
+    Examples:
+        :any:`Inline Bot <examples.inlinebot>`
 
     Args:
         message_text (:obj:`str`): Text of the message to be sent,
-            1-:tg-const:`telegram.constants.MessageLimit.TEXT_LENGTH` characters after entities
+            :tg-const:`telegram.constants.MessageLimit.MIN_TEXT_LENGTH`-
+            :tg-const:`telegram.constants.MessageLimit.MAX_TEXT_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in your bot's message. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        entities (List[:class:`telegram.MessageEntity`], optional): List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`, optional): |parse_mode|
+        entities (List[:class:`telegram.MessageEntity`], optional): |caption_entities|
         disable_web_page_preview (:obj:`bool`, optional): Disables link previews for links in the
             sent message.
-        **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     Attributes:
         message_text (:obj:`str`): Text of the message to be sent,
-            1-:tg-const:`telegram.constants.MessageLimit.TEXT_LENGTH` characters after entities
+            1-:tg-const:`telegram.constants.MessageLimit.MAX_TEXT_LENGTH` characters after entities
             parsing.
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or inline URLs in your bot's message. See the constants
-            in :class:`telegram.constants.ParseMode` for the available modes.
-        entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
-            entities that appear in the caption, which can be specified instead of
-            :paramref:`parse_mode`.
+        parse_mode (:obj:`str`): Optional. |parse_mode|
+        entities (List[:class:`telegram.MessageEntity`]): Optional. |caption_entities|
         disable_web_page_preview (:obj:`bool`): Optional. Disables link previews for links in the
             sent message.
 
@@ -72,8 +65,10 @@ class InputTextMessageContent(InputMessageContent):
         parse_mode: ODVInput[str] = DEFAULT_NONE,
         disable_web_page_preview: ODVInput[bool] = DEFAULT_NONE,
         entities: Union[Tuple[MessageEntity, ...], List[MessageEntity]] = None,
-        **_kwargs: Any,
+        *,
+        api_kwargs: JSONDict = None,
     ):
+        super().__init__(api_kwargs=api_kwargs)
         # Required
         self.message_text = message_text
         # Optionals
@@ -82,12 +77,3 @@ class InputTextMessageContent(InputMessageContent):
         self.disable_web_page_preview = disable_web_page_preview
 
         self._id_attrs = (self.message_text,)
-
-    def to_dict(self) -> JSONDict:
-        """See :meth:`telegram.TelegramObject.to_dict`."""
-        data = super().to_dict()
-
-        if self.entities:
-            data["entities"] = [ce.to_dict() for ce in self.entities]
-
-        return data