Bump version to v13.2

* Update docs & ignore edited channel posts

* typo

* Apply suggestions from code review

Co-authored-by: Poolitzer <25934244+Poolitzer@users.noreply.github.com>

* Update telegram/ext/conversationhandler.py

* fix pre-commit

Co-authored-by: Poolitzer <25934244+Poolitzer@users.noreply.github.com>

.github/CONTRIBUTING.rst

@@ -91,12 +91,16 @@ Here's how to make a one-off code change.
 
      Once the process terminates, you can view the built documentation by opening ``docs/build/html/index.html`` with a browser.
 
-   - For consistency, please conform to `Google Python Style Guide`_ and `Google Python Style Docstrings`_. In addition, code should be formatted consistently with other code around it.
+   - Add ``.. versionadded:: version``, ``.. versionchanged:: version`` or ``.. deprecated:: version`` to the associated documentation of your changes, depending on what kind of change you made. This only applies if the change you made is visible to an end user. The directives should be added to class/method descriptions if their general behaviour changed and to the description of all arguments & attributes that changed.
+
+   - For consistency, please conform to `Google Python Style Guide`_ and `Google Python Style Docstrings`_.
 
    - The following exceptions to the above (Google's) style guides applies:
 
         - Documenting types of global variables and complex types of class members can be done using the Sphinx docstring convention.
 
+   -  In addition, PTB uses the `Black`_ coder formatting. Plugins for Black exist for some `popular editors`_. You can use those instead of manually formatting everything.
+
    - Please ensure that the code you write is well-tested.
 
    - Don’t break backward compatibility.
@@ -189,11 +193,6 @@ Here's how to make a one-off code change.
 Style commandments
 ------------------
 
-Specific commandments
-#####################
-
-- Avoid using "double quotes" where you can reasonably use 'single quotes'.
-
 Assert comparison order
 #######################
 
@@ -255,3 +254,5 @@ break the API classes. For example:
 .. _AUTHORS.rst: ../AUTHORS.rst
 .. _`MyPy`: https://mypy.readthedocs.io/en/stable/index.html
 .. _`here`: https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html
+.. _`Black`: https://black.readthedocs.io/en/stable/index.html
+.. _`popular editors`: https://black.readthedocs.io/en/stable/editor_integration.html

.github/pull_request_template.md

@@ -0,0 +1,30 @@
+<!--
+Hey! You're PRing? Cool! Please have a look at the below checklist. It's here to help both you and the maintainers to remember some aspects. Make sure to check out our contribution guide (https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst).
+-->
+
+### Checklist for PRs
+
+- [ ] Added `.. versionadded:: version`, `.. versionchanged:: version` or `.. deprecated:: version` to the docstrings for user facing changes (for methods/class descriptions, arguments and attributes)
+- [ ] Created new or adapted existing unit tests
+- [ ] Added myself alphabetically to `AUTHORS.rst` (optional)
+
+
+### If the PR contains API changes (otherwise, you can delete this passage)
+
+* New classes:
+    - [ ] Added `self._id_attrs` and corresponding documentation
+    - [ ] `__init__` accepts `**_kwargs`
+    
+* 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
+    - [ ] Added new handlers for new update types
+    - [ ] Added new filters for new message (sub)types
+    - [ ] Added or updated documentation for the changed class(es) and/or method(s)
+    - [ ] Updated the Bot API version number in all places in `README.rst` and `README_RAW.rst`, including the badge

.github/workflows/readme_notifier.yml

@@ -0,0 +1,16 @@
+name: Warning maintainers
+on:
+  pull_request:
+    paths:
+      - README.rst
+      - README_RAW.rst
+jobs:
+  job:
+    runs-on: ubuntu-latest
+    name: about readme change
+    steps:
+      - name: running the check
+        uses: Poolitzer/notifier-action@master
+        with:
+          notify-message: Hey! Looks like you edited README.rst or README_RAW.rst. I'm just a friendly reminder to apply relevant changes to both of those files :)
+          repo-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test.yml

@@ -3,8 +3,6 @@ on:
   pull_request:
     branches:
       - master
-  schedule:
-    - cron: 7 3 * * *
   push:
     branches: 
       - master
@@ -15,8 +13,8 @@ jobs:
     runs-on: ${{matrix.os}}
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8]
-        os: [ubuntu-latest, windows-latest]
+        python-version: [3.6, 3.7, 3.8, 3.9]
+        os: [ubuntu-latest, windows-latest, macos-latest]
         include:
           - os: ubuntu-latest
             python-version: 3.7
@@ -31,7 +29,7 @@ jobs:
         run:
           git submodule update --init --recursive
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v1
+        uses: actions/setup-python@v2
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
@@ -57,13 +55,11 @@ jobs:
         shell: bash --noprofile --norc {0}
 
       - name: Submit coverage
-        run: |
-          if [ "$CODECOV_TOKEN" != "" ]; then
-             codecov -F github -t $CODECOV_TOKEN --name "${{ matrix.os }}-${{ matrix.python-version }}"
-          fi
-        env:
-          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-        shell: bash
+        uses: codecov/codecov-action@v1.0.13
+        with:
+          env_vars: OS,PYTHON
+          name: ${{ matrix.os }}-${{ matrix.python-version }}
+          fail_ci_if_error: true
   test_official:
     name: test-official
     runs-on: ${{matrix.os}}

.gitignore

@@ -84,3 +84,6 @@ telegram.jpg
 
 # Exclude .exrc file for Vim
 .exrc
+
+# virtual env
+venv*

.pre-commit-config.yaml

@@ -1,25 +1,34 @@
+# Make sure that
+#   * the revs specified here match requirements-dev.txt
+#   * the makefile checks the same files as pre-commit
 repos:
--   repo: git://github.com/python-telegram-bot/mirrors-yapf
-    rev: 5769e088ef6e0a0d1eb63bd6d0c1fe9f3606d6c8
+-   repo: https://github.com/psf/black
+    rev: 20.8b1
     hooks:
-    -   id: yapf
-        files: ^(telegram|tests)/.*\.py$
+    -   id: black
         args:
         - --diff
+        - --check
 -   repo: https://gitlab.com/pycqa/flake8
-    rev: 3.8.1
+    rev: 3.8.4
     hooks:
     -   id: flake8
--   repo: git://github.com/pre-commit/mirrors-pylint
-    rev: v2.5.3
+-   repo: https://github.com/PyCQA/pylint
+    rev: pylint-2.6.0
     hooks:
     -   id: pylint
-        files: ^telegram/.*\.py$
+        files: ^(telegram|examples)/.*\.py$
         args:
-        - --errors-only
-        - --disable=import-error
+        - --rcfile=setup.cfg
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: 'v0.770'
+    rev: v0.790
     hooks:
     -   id: mypy
-        files: ^telegram/.*\.py$
+        files: ^(telegram|examples)/.*\.py$
+-   repo: https://github.com/asottile/pyupgrade
+    rev: v2.7.4
+    hooks:
+    -   id: pyupgrade
+        files: ^(telegram|examples|tests)/.*\.py$
+        args:
+            - --py36-plus

AUTHORS.rst

@@ -2,9 +2,12 @@ Credits
 =======
 
 ``python-telegram-bot`` was originally created by
-`Leandro Toledo <https://github.com/leandrotoledo>`_ and is now maintained by
+`Leandro Toledo <https://github.com/leandrotoledo>`_ and is now maintained by `Hinrich Mahler <https://github.com/Bibo-Joshi>`_.
+Emeritus maintainers include
 `Jannes Höke <https://github.com/jh0ker>`_ (`@jh0ker <https://t.me/jh0ker>`_ on Telegram),
-`Noam Meltzer <https://github.com/tsnoam>`_, `Pieter Schutz <https://github.com/eldinnie>`_, `Jasmin Bom <https://github.com/jsmnbom>`_ and `Hinrich Mahler <https://github.com/Bibo-Joshi>`_.
+`Noam Meltzer <https://github.com/tsnoam>`_, `Pieter Schutz <https://github.com/eldinnie>`_ and `Jasmin Bom <https://github.com/jsmnbom>`_.
+
+The maintainers are actively supported by `Poolitzer <https://github.com/Poolitzer>`_ in terms of development and community liaison.
 
 We're vendoring urllib3 as part of ``python-telegram-bot`` which is distributed under the MIT
 license. For more info, full credits & license terms, the sources can be found here:
@@ -36,9 +39,11 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Eugene Lisitsky <https://github.com/lisitsky>`_
 - `Eugenio Panadero <https://github.com/azogue>`_
 - `Evan Haberecht <https://github.com/habereet>`_
+- `Evgeny Denisov <https://github.com/eIGato>`_
 - `evgfilim1 <https://github.com/evgfilim1>`_
 - `franciscod <https://github.com/franciscod>`_
 - `gamgi <https://github.com/gamgi>`_
+- `Gauthamram Ravichandran <https://github.com/GauthamramRavichandran>`_
 - `Harshil <https://github.com/harshil21>`_
 - `Hugo Damer <https://github.com/HakimusGIT>`_
 - `ihoru <https://github.com/ihoru>`_
@@ -58,10 +63,12 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Loo Zheng Yuan <https://github.com/loozhengyuan>`_
 - `LRezende <https://github.com/lrezende>`_
 - `macrojames <https://github.com/macrojames>`_
+- `Matheus Lemos <https://github.com/mlemosf>`_
 - `Michael Elovskikh <https://github.com/wronglink>`_
 - `Mischa Krüger <https://github.com/Makman2>`_
 - `naveenvhegde <https://github.com/naveenvhegde>`_
 - `neurrone <https://github.com/neurrone>`_
+- `NikitaPirate <https://github.com/NikitaPirate>`_
 - `njittam <https://github.com/njittam>`_
 - `Noam Meltzer <https://github.com/tsnoam>`_
 - `Oleg Shlyazhko <https://github.com/ollmer>`_
@@ -72,6 +79,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Paul Larsen <https://github.com/PaulSonOfLars>`_
 - `Pieter Schutz <https://github.com/eldinnie>`_
 - `Poolitzer <https://github.com/Poolitzer>`_
+- `Pranjalya Tiwari <https://github.com/Pranjalya>`_
 - `Rahiel Kasim <https://github.com/rahiel>`_
 - `Riko Naka <https://github.com/rikonaka>`_
 - `Rizlas <https://github.com/rizlas>`_
@@ -82,6 +90,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `sooyhwang <https://github.com/sooyhwang>`_
 - `syntx <https://github.com/syntx>`_
 - `thodnev <https://github.com/thodnev>`_
+- `Timur Kushukov <https://github.com/timqsh>`_
 - `Trainer Jono <https://github.com/Tr-Jono>`_
 - `Valentijn <https://github.com/Faalentijn>`_
 - `voider1 <https://github.com/voider1>`_

CHANGES.rst

@@ -2,6 +2,158 @@
 Changelog
 =========
 
+Version 13.2
+============
+*Released 2021-02-02*
+
+**Major Changes:**
+
+- Introduce ``python-telegram-bot-raw`` (`#2324`_)
+- Explicit Signatures for Shortcuts (`#2240`_)
+
+**New Features:**
+
+- Add Missing Shortcuts to ``Message`` (`#2330`_)
+- Rich Comparison for ``Bot`` (`#2320`_)
+- Add ``run_async`` Parameter to ``ConversationHandler`` (`#2292`_)
+- Add New Shortcuts to ``Chat`` (`#2291`_)
+- Add New Constant ``MAX_ANSWER_CALLBACK_QUERY_TEXT_LENGTH`` (`#2282`_)
+- Allow Passing Custom Filename For All Media (`#2249`_)
+- Handle Bytes as File Input (`#2233`_)
+
+**Bug Fixes:**
+
+- Fix Escaping in Nested Entities in ``Message`` Properties (`#2312`_)
+- Adjust Calling of ``Dispatcher.update_persistence`` (`#2285`_)
+- Add ``quote`` kwarg to ``Message.reply_copy`` (`#2232`_)
+- ``ConversationHandler``: Docs & ``edited_channel_post`` behavior (`#2339`_)
+
+**Minor changes, CI improvements, doc fixes and type hinting:**
+
+- Doc Fixes (`#2253`_, `#2225`_)
+- Reduce Usage of ``typing.Any`` (`#2321`_)
+- Extend Deeplinking Example (`#2335`_)
+- Add pyupgrade to pre-commit Hooks (`#2301`_)
+- Add PR Template (`#2299`_)
+- Drop Nightly Tests & Update Badges (`#2323`_)
+- Update Copyright (`#2289`_, `#2287`_)
+- Change Order of Class DocStrings (`#2256`_)
+- Add macOS to Test Matrix (`#2266`_)
+- Start Using Versioning Directives in Docs (`#2252`_)
+- Improve Annotations & Docs of Handlers (`#2243`_)
+
+.. _`#2324`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2324
+.. _`#2240`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2240
+.. _`#2330`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2330
+.. _`#2320`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2320
+.. _`#2292`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2292
+.. _`#2291`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2291
+.. _`#2282`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2282
+.. _`#2249`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2249
+.. _`#2233`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2233
+.. _`#2312`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2312
+.. _`#2285`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2285
+.. _`#2232`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2232
+.. _`#2339`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2339
+.. _`#2253`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2253
+.. _`#2225`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2225
+.. _`#2321`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2321
+.. _`#2335`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2335
+.. _`#2301`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2301
+.. _`#2299`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2299
+.. _`#2323`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2323
+.. _`#2289`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2289
+.. _`#2287`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2287
+.. _`#2256`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2256
+.. _`#2266`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2266
+.. _`#2252`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2252
+.. _`#2243`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2243
+
+Version 13.1
+============
+*Released 2020-11-29*
+
+**Major Changes:**
+
+- Full support of Bot API 5.0 (`#2181`_, `#2186`_, `#2190`_, `#2189`_, `#2183`_, `#2184`_, `#2188`_, `#2185`_, `#2192`_, `#2196`_, `#2193`_, `#2223`_, `#2199`_, `#2187`_, `#2147`_, `#2205`_)
+
+**New Features:**
+
+- Add ``Defaults.run_async`` (`#2210`_)
+- Improve and Expand ``CallbackQuery`` Shortcuts (`#2172`_)
+- Add XOR Filters and make ``Filters.name`` a Property (`#2179`_)
+- Add ``Filters.document.file_extension`` (`#2169`_)
+- Add ``Filters.caption_regex`` (`#2163`_)
+- Add ``Filters.chat_type`` (`#2128`_)
+- Handle Non-Binary File Input (`#2202`_)
+
+**Bug Fixes:**
+
+- Improve Handling of Custom Objects in ``BasePersistence.insert``/``replace_bot`` (`#2151`_)
+- Fix bugs in ``replace/insert_bot`` (`#2218`_)
+
+**Minor changes, CI improvements, doc fixes and type hinting:**
+
+- Improve Type hinting (`#2204`_, `#2118`_, `#2167`_, `#2136`_)
+- Doc Fixes & Extensions (`#2201`_, `#2161`_)
+- Use F-Strings Where Possible (`#2222`_)
+- Rename kwargs to _kwargs where possible (`#2182`_)
+- Comply with PEP561 (`#2168`_)
+- Improve Code Quality (`#2131`_)
+- Switch Code Formatting to Black (`#2122`_, `#2159`_, `#2158`_)
+- Update Wheel Settings (`#2142`_)
+- Update ``timerbot.py`` to ``v13.0`` (`#2149`_)
+- Overhaul Constants (`#2137`_)
+- Add Python 3.9 to Test Matrix (`#2132`_)
+- Switch Codecov to ``GitHub`` Action (`#2127`_)
+- Specify Required pytz Version (`#2121`_)
+
+
+.. _`#2181`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2181
+.. _`#2186`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2186
+.. _`#2190`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2190
+.. _`#2189`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2189
+.. _`#2183`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2183
+.. _`#2184`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2184
+.. _`#2188`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2188
+.. _`#2185`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2185
+.. _`#2192`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2192
+.. _`#2196`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2196
+.. _`#2193`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2193
+.. _`#2223`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2223
+.. _`#2199`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2199
+.. _`#2187`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2187
+.. _`#2147`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2147
+.. _`#2205`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2205
+.. _`#2210`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2210
+.. _`#2172`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2172
+.. _`#2179`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2179
+.. _`#2169`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2169
+.. _`#2163`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2163
+.. _`#2128`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2128
+.. _`#2202`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2202
+.. _`#2151`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2151
+.. _`#2218`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2218
+.. _`#2204`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2204
+.. _`#2118`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2118
+.. _`#2167`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2167
+.. _`#2136`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2136
+.. _`#2201`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2201
+.. _`#2161`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2161
+.. _`#2222`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2222
+.. _`#2182`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2182
+.. _`#2168`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2168
+.. _`#2131`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2131
+.. _`#2122`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2122
+.. _`#2159`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2159
+.. _`#2158`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2158
+.. _`#2142`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2142
+.. _`#2149`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2149
+.. _`#2137`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2137
+.. _`#2132`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2132
+.. _`#2127`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2127
+.. _`#2121`: https://github.com/python-telegram-bot/python-telegram-bot/pull/2121
+
 Version 13.0
 ============
 *Released 2020-10-07*

MANIFEST.in

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

Makefile

@@ -1,11 +1,10 @@
 .DEFAULT_GOAL := help
-.PHONY: clean pep257 pep8 yapf lint test install
+.PHONY: clean pep8 black lint test install
 
 PYLINT          := pylint
 PYTEST          := pytest
-PEP257          := pep257
 PEP8            := flake8
-YAPF            := yapf
+BLACK           := black
 MYPY            := mypy
 PIP             := pip
 
@@ -15,22 +14,20 @@ clean:
 	find . -name '*.pyc' -exec rm -f {} \;
 	find . -name '*.pyo' -exec rm -f {} \;
 	find . -name '*~' -exec rm -f {} \;
-	find . -regex "./telegram.\(mp3\|mp4\|ogg\|png\|webp\)" -exec rm {} \;
-
-pep257:
-	$(PEP257) telegram
+	find . -regex "./telegram[0-9]*.\(jpg\|mp3\|mp4\|ogg\|png\|webp\)" -exec rm {} \;
 
 pep8:
-	$(PEP8) telegram
+	$(PEP8) telegram tests examples
 
-yapf:
-	$(YAPF) -r telegram
+black:
+	$(BLACK) .
 
 lint:
-	$(PYLINT) -E telegram --disable=no-name-in-module,import-error
+	$(PYLINT) --rcfile=setup.cfg telegram examples
 
 mypy:
 	$(MYPY) -p telegram
+	$(MYPY) examples
 
 test:
 	$(PYTEST) -v
@@ -41,18 +38,16 @@ install:
 help:
 	@echo "Available targets:"
 	@echo "- clean       Clean up the source directory"
-	@echo "- pep257      Check docstring style with pep257"
 	@echo "- pep8        Check style with flake8"
 	@echo "- lint        Check style with pylint"
-	@echo "- yapf        Check style with yapf"
+	@echo "- black       Check style with black"
 	@echo "- mypy        Check type hinting with mypy"
 	@echo "- test        Run tests using pytest"
 	@echo
 	@echo "Available variables:"
 	@echo "- PYLINT      default: $(PYLINT)"
 	@echo "- PYTEST      default: $(PYTEST)"
-	@echo "- PEP257      default: $(PEP257)"
 	@echo "- PEP8        default: $(PEP8)"
-	@echo "- YAPF        default: $(YAPF)"
+	@echo "- BLACK       default: $(BLACK)"
 	@echo "- MYPY        default: $(MYPY)"
 	@echo "- PIP         default: $(PIP)"

README.rst

@@ -1,3 +1,6 @@
+..
+    Make user to apply any changes to this file to README_RAW.rst as well!
+
 .. image:: https://github.com/python-telegram-bot/logos/blob/master/logo-text/png/ptb-logo-text_768.png?raw=true
    :align: center
    :target: https://python-telegram-bot.org
@@ -17,26 +20,30 @@ We have a vibrant community of developers helping each other in our `Telegram gr
    :target: https://pypi.org/project/python-telegram-bot/
    :alt: Supported Python versions
 
-.. image:: https://cpu.re/static/python-telegram-bot/downloads.svg
-   :target: https://www.cpu.re/static/python-telegram-bot/downloads-by-python-version.txt
+.. image:: https://img.shields.io/badge/Bot%20API-5.0-blue?logo=telegram
+   :target: https://core.telegram.org/bots/api-changelog
+   :alt: Supported Bot API versions
+
+.. image:: https://img.shields.io/pypi/dm/python-telegram-bot
+   :target: https://pypistats.org/packages/python-telegram-bot
    :alt: PyPi Package Monthly Download
 
-.. image:: https://img.shields.io/badge/docs-latest-af1a97.svg
-   :target: https://python-telegram-bot.readthedocs.io/
+.. image:: https://readthedocs.org/projects/python-telegram-bot/badge/?version=stable
+   :target: https://python-telegram-bot.readthedocs.io/en/stable/?badge=stable
    :alt: Documentation Status
 
 .. image:: https://img.shields.io/pypi/l/python-telegram-bot.svg
    :target: https://www.gnu.org/licenses/lgpl-3.0.html
    :alt: LGPLv3 License
 
-.. image:: https://github.com/python-telegram-bot/python-telegram-bot/workflows/GitHub%20Actions/badge.svg?event=schedule
+.. image:: https://github.com/python-telegram-bot/python-telegram-bot/workflows/GitHub%20Actions/badge.svg
    :target: https://github.com/python-telegram-bot/python-telegram-bot/
    :alt: Github Actions workflow
 
 .. image:: https://codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/python-telegram-bot/python-telegram-bot
    :alt: Code coverage
-   
+
 .. image:: http://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg
    :target: http://isitmaintained.com/project/python-telegram-bot/python-telegram-bot
    :alt: Median time to resolve an issue
@@ -45,7 +52,10 @@ We have a vibrant community of developers helping each other in our `Telegram gr
    :target: https://www.codacy.com/app/python-telegram-bot/python-telegram-bot?utm_source=github.com&utm_medium=referral&utm_content=python-telegram-bot/python-telegram-bot&utm_campaign=Badge_Grade
    :alt: Code quality
 
-.. image:: https://img.shields.io/badge/Telegram-Group-blue.svg
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/psf/black
+
+.. image:: https://img.shields.io/badge/Telegram-Group-blue.svg?logo=telegram
    :target: https://telegram.me/pythontelegrambotgroup
    :alt: Telegram Group
 
@@ -89,11 +99,19 @@ In addition to the pure API implementation, this library features a number of hi
 make the development of bots easy and straightforward. These classes are contained in the
 ``telegram.ext`` submodule.
 
+A pure API implementation *without* ``telegram.ext`` is available as the standalone package ``python-telegram-bot-raw``.  `See here for details. <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/README_RAW.rst>`_
+
+----
+Note
+----
+
+Installing both ``python-telegram-bot`` and ``python-telegram-bot-raw`` in conjunction will result in undesired side-effects, so only install *one* of both.
+
 ====================
 Telegram API support
 ====================
 
-All types and methods of the Telegram Bot API **4.8** are supported.
+All types and methods of the Telegram Bot API **5.0** are supported.
 
 ==========
 Installing
@@ -189,14 +207,13 @@ You can get help in several ways:
 
 2. In case you are unable to join our group due to Telegram restrictions, you can use our `IRC channel <https://webchat.freenode.net/?channels=##python-telegram-bot>`_.
 
-3. Report bugs, request new features or ask questions by `creating an issue <https://github.com/python-telegram-bot/python-telegram-bot/issues/new/choose>`_.
+3. Report bugs, request new features or ask questions by `creating an issue <https://github.com/python-telegram-bot/python-telegram-bot/issues/new/choose>`_ or `a discussion <https://github.com/python-telegram-bot/python-telegram-bot/discussions/new>`_.
 
 4. Our `Wiki pages <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ offer a growing amount of resources.
 
 5. You can even ask for help on Stack Overflow using the `python-telegram-bot tag <https://stackoverflow.com/questions/tagged/python-telegram-bot>`_.
 
 
-
 ============
 Contributing
 ============

README_RAW.rst

@@ -0,0 +1,210 @@
+..
+    Make user to apply any changes to this file to README.rst as well!
+
+.. image:: https://github.com/python-telegram-bot/logos/blob/master/logo-text/png/ptb-raw-logo-text_768.png?raw=true
+   :align: center
+   :target: https://python-telegram-bot.org
+   :alt: python-telegram-bot-raw Logo
+
+We have made you a wrapper you can't refuse
+
+We have a vibrant community of developers helping each other in our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_. Join us!
+
+*Stay tuned for library updates and new releases on our* `Telegram Channel <https://telegram.me/pythontelegrambotchannel>`_.
+
+.. image:: https://img.shields.io/pypi/v/python-telegram-bot-raw.svg
+   :target: https://pypi.org/project/python-telegram-bot/
+   :alt: PyPi Package Version
+
+.. image:: https://img.shields.io/pypi/pyversions/python-telegram-bot-raw.svg
+   :target: https://pypi.org/project/python-telegram-bot/
+   :alt: Supported Python versions
+
+.. image:: https://img.shields.io/badge/Bot%20API-5.0-blue?logo=telegram
+   :target: https://core.telegram.org/bots/api-changelog
+   :alt: Supported Bot API versions
+
+.. image:: https://img.shields.io/pypi/dm/python-telegram-bot-raw
+   :target: https://pypistats.org/packages/python-telegram-bot
+   :alt: PyPi Package Monthly Download
+
+.. image:: https://img.shields.io/badge/docs-latest-af1a97.svg
+   :target: https://python-telegram-bot.readthedocs.io/
+   :alt: Documentation Status
+
+.. image:: https://img.shields.io/pypi/l/python-telegram-bot-raw.svg
+   :target: https://www.gnu.org/licenses/lgpl-3.0.html
+   :alt: LGPLv3 License
+
+.. image:: https://github.com/python-telegram-bot/python-telegram-bot/workflows/GitHub%20Actions/badge.svg
+   :target: https://github.com/python-telegram-bot/python-telegram-bot/
+   :alt: Github Actions workflow
+
+.. image:: https://codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg
+   :target: https://codecov.io/gh/python-telegram-bot/python-telegram-bot
+   :alt: Code coverage
+
+.. image:: http://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg
+   :target: http://isitmaintained.com/project/python-telegram-bot/python-telegram-bot
+   :alt: Median time to resolve an issue
+
+.. image:: https://api.codacy.com/project/badge/Grade/99d901eaa09b44b4819aec05c330c968
+   :target: https://www.codacy.com/app/python-telegram-bot/python-telegram-bot?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=python-telegram-bot/python-telegram-bot&amp;utm_campaign=Badge_Grade
+   :alt: Code quality
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/psf/black
+
+.. image:: https://img.shields.io/badge/Telegram-Group-blue.svg?logo=telegram
+   :target: https://telegram.me/pythontelegrambotgroup
+   :alt: Telegram Group
+
+.. image:: https://img.shields.io/badge/IRC-Channel-blue.svg
+   :target: https://webchat.freenode.net/?channels=##python-telegram-bot
+   :alt: IRC Bridge
+
+=================
+Table of contents
+=================
+
+- `Introduction`_
+
+- `Telegram API support`_
+
+- `Installing`_
+
+- `Getting started`_
+
+  #. `Logging`_
+
+  #. `Documentation`_
+
+- `Getting help`_
+
+- `Contributing`_
+
+- `License`_
+
+============
+Introduction
+============
+
+This library provides a pure Python, lightweight interface for the
+`Telegram Bot API <https://core.telegram.org/bots/api>`_.
+It's compatible with Python versions 3.6+. PTB-Raw might also work on `PyPy <http://pypy.org/>`_, though there have been a lot of issues before. Hence, PyPy is not officially supported.
+
+``python-telegram-bot-raw`` is part of the `python-telegram-bot <https://python-telegram-bot.org>`_ ecosystem and provides the pure API functionality extracted from PTB. It therefore does *not* have independent release schedules, changelogs or documentation. Please consult the PTB resources.
+
+----
+Note
+----
+
+Installing both ``python-telegram-bot`` and ``python-telegram-bot-raw`` in conjunction will result in undesired side-effects, so only install *one* of both.
+
+====================
+Telegram API support
+====================
+
+All types and methods of the Telegram Bot API **5.0** are supported.
+
+==========
+Installing
+==========
+
+You can install or upgrade python-telegram-bot-raw with:
+
+.. code:: shell
+
+    $ pip install python-telegram-bot-raw --upgrade
+
+Or you can install from source with:
+
+.. code:: shell
+
+    $ git clone https://github.com/python-telegram-bot/python-telegram-bot --recursive
+    $ cd python-telegram-bot
+    $ python setup-raw.py install
+
+In case you have a previously cloned local repository already, you should initialize the added urllib3 submodule before installing with:
+
+.. code:: shell
+
+    $ git submodule update --init --recursive
+
+----
+Note
+----
+
+Installing the `.tar.gz` archive available on PyPi directly via `pip` will *not* work as expected, as `pip` does not recognize that it should use `setup-raw.py` instead of `setup.py`.
+
+===============
+Getting started
+===============
+
+Our Wiki contains an `Introduction to the API <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Introduction-to-the-API>`_. Other references are:
+
+- the `Telegram API documentation <https://core.telegram.org/bots/api>`_
+- the `python-telegram-bot documentation <https://python-telegram-bot.readthedocs.io/>`_
+
+-------
+Logging
+-------
+
+This library uses the ``logging`` module. To set up logging to standard output, put:
+
+.. code:: python
+
+    import logging
+    logging.basicConfig(level=logging.DEBUG,
+                        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+
+at the beginning of your script.
+
+You can also use logs in your application by calling ``logging.getLogger()`` and setting the log level you want:
+
+.. code:: python
+
+    logger = logging.getLogger()
+    logger.setLevel(logging.INFO)
+
+If you want DEBUG logs instead:
+
+.. code:: python
+
+    logger.setLevel(logging.DEBUG)
+
+
+=============
+Documentation
+=============
+
+``python-telegram-bot``'s documentation lives at `readthedocs.io <https://python-telegram-bot.readthedocs.io/>`_, which
+includes the relevant documentation for ``python-telegram-bot-raw``.
+
+============
+Getting help
+============
+
+You can get help in several ways:
+
+1. We have a vibrant community of developers helping each other in our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_. Join us!
+
+2. In case you are unable to join our group due to Telegram restrictions, you can use our `IRC channel <https://webchat.freenode.net/?channels=##python-telegram-bot>`_.
+
+3. Report bugs, request new features or ask questions by `creating an issue <https://github.com/python-telegram-bot/python-telegram-bot/issues/new/choose>`_ or `a discussion <https://github.com/python-telegram-bot/python-telegram-bot/discussions/new>`_.
+
+4. Our `Wiki pages <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ offer a growing amount of resources.
+
+5. You can even ask for help on Stack Overflow using the `python-telegram-bot tag <https://stackoverflow.com/questions/tagged/python-telegram-bot>`_.
+
+============
+Contributing
+============
+
+Contributions of all sizes are welcome. Please review our `contribution guidelines <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst>`_ to get started. You can also help by `reporting bugs <https://github.com/python-telegram-bot/python-telegram-bot/issues/new>`_.
+
+=======
+License
+=======
+
+You may copy, distribute and modify the software provided that modifications are described and licensed for free under `LGPL-3 <https://www.gnu.org/licenses/lgpl-3.0.html>`_. Derivatives works (including modifications or anything statically linked to the library) can only be redistributed under LGPL-3, but applications that use the library don't have to be.

docs/source/conf.py

@@ -50,7 +50,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Python Telegram Bot'
-copyright = u'2015-2020, Leandro Toledo'
+copyright = u'2015-2021, Leandro Toledo'
 author = u'Leandro Toledo'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -58,9 +58,9 @@ author = u'Leandro Toledo'
 # built documents.
 #
 # The short X.Y version.
-version = '13.0'  # telegram.__version__[:3]
+version = '13.2'  # telegram.__version__[:3]
 # The full version, including alpha/beta/rc tags.
-release = '13.0'  # telegram.__version__
+release = '13.2'  # telegram.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/telegram.chatlocation.rst

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

docs/source/telegram.ext.rst

@@ -6,13 +6,12 @@ telegram.ext package
     telegram.ext.updater
     telegram.ext.dispatcher
     telegram.ext.dispatcherhandlerstop
-    telegram.ext.filters
+    telegram.ext.callbackcontext
+    telegram.ext.defaults
     telegram.ext.job
     telegram.ext.jobqueue
     telegram.ext.messagequeue
     telegram.ext.delayqueue
-    telegram.ext.callbackcontext
-    telegram.ext.defaults
 
 Handlers
 --------
@@ -22,10 +21,11 @@ Handlers
     telegram.ext.handler
     telegram.ext.callbackqueryhandler
     telegram.ext.choseninlineresulthandler
-    telegram.ext.conversationhandler
     telegram.ext.commandhandler
+    telegram.ext.conversationhandler
     telegram.ext.inlinequeryhandler
     telegram.ext.messagehandler
+    telegram.ext.filters
     telegram.ext.pollanswerhandler
     telegram.ext.pollhandler
     telegram.ext.precheckoutqueryhandler
@@ -43,4 +43,11 @@ Persistence
 
     telegram.ext.basepersistence
     telegram.ext.picklepersistence
-    telegram.ext.dictpersistence
+    telegram.ext.dictpersistence
+
+utils
+-----
+
+.. toctree::
+
+    telegram.ext.utils.promise

docs/source/telegram.ext.utils.promise.rst

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

docs/source/telegram.messageid.rst

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

docs/source/telegram.proximityalerttriggered.rst

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

docs/source/telegram.rst

@@ -13,6 +13,7 @@ telegram package
     telegram.callbackquery
     telegram.chat
     telegram.chataction
+    telegram.chatlocation
     telegram.chatmember
     telegram.chatpermissions
     telegram.chatphoto
@@ -37,12 +38,14 @@ telegram package
     telegram.location
     telegram.loginurl
     telegram.message
+    telegram.messageid
     telegram.messageentity
     telegram.parsemode
     telegram.photosize
     telegram.poll
     telegram.pollanswer
     telegram.polloption
+    telegram.proximityalerttriggered
     telegram.replykeyboardremove
     telegram.replykeyboardmarkup
     telegram.replymarkup

docs/source/telegram.utils.promise.rst

@@ -1,6 +1,9 @@
 telegram.utils.promise.Promise
 ==============================
 
-.. autoclass:: telegram.utils.promise.Promise
-    :members:
-    :show-inheritance:
+.. py:class:: telegram.utils.promise.Promise
+
+   Shortcut for :class:`telegram.ext.utils.promise.Promise`.
+
+   .. deprecated:: 13.2
+      Use :class:`telegram.ext.utils.promise.Promise` instead.

examples/conversationbot.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
+# pylint: disable=W0613, C0116
+# type: ignore[union-attr]
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -16,82 +17,97 @@ bot.
 
 import logging
 
-from telegram import (ReplyKeyboardMarkup, ReplyKeyboardRemove)
-from telegram.ext import (Updater, CommandHandler, MessageHandler, Filters,
-                          ConversationHandler)
+from telegram import ReplyKeyboardMarkup, ReplyKeyboardRemove, Update
+from telegram.ext import (
+    Updater,
+    CommandHandler,
+    MessageHandler,
+    Filters,
+    ConversationHandler,
+    CallbackContext,
+)
 
 # Enable logging
-logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-                    level=logging.INFO)
+logging.basicConfig(
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', level=logging.INFO
+)
 
 logger = logging.getLogger(__name__)
 
 GENDER, PHOTO, LOCATION, BIO = range(4)
 
 
-def start(update, context):
+def start(update: Update, context: CallbackContext) -> int:
     reply_keyboard = [['Boy', 'Girl', 'Other']]
 
     update.message.reply_text(
         'Hi! My name is Professor Bot. I will hold a conversation with you. '
         'Send /cancel to stop talking to me.\n\n'
         'Are you a boy or a girl?',
-        reply_markup=ReplyKeyboardMarkup(reply_keyboard, one_time_keyboard=True))
+        reply_markup=ReplyKeyboardMarkup(reply_keyboard, one_time_keyboard=True),
+    )
 
     return GENDER
 
 
-def gender(update, context):
+def gender(update: Update, context: CallbackContext) -> int:
     user = update.message.from_user
     logger.info("Gender of %s: %s", user.first_name, update.message.text)
-    update.message.reply_text('I see! Please send me a photo of yourself, '
-                              'so I know what you look like, or send /skip if you don\'t want to.',
-                              reply_markup=ReplyKeyboardRemove())
+    update.message.reply_text(
+        'I see! Please send me a photo of yourself, '
+        'so I know what you look like, or send /skip if you don\'t want to.',
+        reply_markup=ReplyKeyboardRemove(),
+    )
 
     return PHOTO
 
 
-def photo(update, context):
+def photo(update: Update, context: CallbackContext) -> int:
     user = update.message.from_user
     photo_file = update.message.photo[-1].get_file()
     photo_file.download('user_photo.jpg')
     logger.info("Photo of %s: %s", user.first_name, 'user_photo.jpg')
-    update.message.reply_text('Gorgeous! Now, send me your location please, '
-                              'or send /skip if you don\'t want to.')
+    update.message.reply_text(
+        'Gorgeous! Now, send me your location please, ' 'or send /skip if you don\'t want to.'
+    )
 
     return LOCATION
 
 
-def skip_photo(update, context):
+def skip_photo(update: Update, context: CallbackContext) -> int:
     user = update.message.from_user
     logger.info("User %s did not send a photo.", user.first_name)
-    update.message.reply_text('I bet you look great! Now, send me your location please, '
-                              'or send /skip.')
+    update.message.reply_text(
+        'I bet you look great! Now, send me your location please, ' 'or send /skip.'
+    )
 
     return LOCATION
 
 
-def location(update, context):
+def location(update: Update, context: CallbackContext) -> int:
     user = update.message.from_user
     user_location = update.message.location
-    logger.info("Location of %s: %f / %f", user.first_name, user_location.latitude,
-                user_location.longitude)
-    update.message.reply_text('Maybe I can visit you sometime! '
-                              'At last, tell me something about yourself.')
+    logger.info(
+        "Location of %s: %f / %f", user.first_name, user_location.latitude, user_location.longitude
+    )
+    update.message.reply_text(
+        'Maybe I can visit you sometime! ' 'At last, tell me something about yourself.'
+    )
 
     return BIO
 
 
-def skip_location(update, context):
+def skip_location(update: Update, context: CallbackContext) -> int:
     user = update.message.from_user
     logger.info("User %s did not send a location.", user.first_name)
-    update.message.reply_text('You seem a bit paranoid! '
-                              'At last, tell me something about yourself.')
+    update.message.reply_text(
+        'You seem a bit paranoid! ' 'At last, tell me something about yourself.'
+    )
 
     return BIO
 
 
-def bio(update, context):
+def bio(update: Update, context: CallbackContext) -> int:
     user = update.message.from_user
     logger.info("Bio of %s: %s", user.first_name, update.message.text)
     update.message.reply_text('Thank you! I hope we can talk again some day.')
@@ -99,44 +115,39 @@ def bio(update, context):
     return ConversationHandler.END
 
 
-def cancel(update, context):
+def cancel(update: Update, context: CallbackContext) -> int:
     user = update.message.from_user
     logger.info("User %s canceled the conversation.", user.first_name)
-    update.message.reply_text('Bye! I hope we can talk again some day.',
-                              reply_markup=ReplyKeyboardRemove())
+    update.message.reply_text(
+        'Bye! I hope we can talk again some day.', reply_markup=ReplyKeyboardRemove()
+    )
 
     return ConversationHandler.END
 
 
-def main():
+def main() -> None:
     # Create the Updater and pass it your bot's token.
-    # Make sure to set use_context=True to use the new context based callbacks
-    # Post version 12 this will no longer be necessary
-    updater = Updater("TOKEN", use_context=True)
+    updater = Updater("TOKEN")
 
     # Get the dispatcher to register handlers
-    dp = updater.dispatcher
+    dispatcher = updater.dispatcher
 
     # Add conversation handler with the states GENDER, PHOTO, LOCATION and BIO
     conv_handler = ConversationHandler(
         entry_points=[CommandHandler('start', start)],
-
         states={
             GENDER: [MessageHandler(Filters.regex('^(Boy|Girl|Other)$'), gender)],
-
-            PHOTO: [MessageHandler(Filters.photo, photo),
-                    CommandHandler('skip', skip_photo)],
-
-            LOCATION: [MessageHandler(Filters.location, location),
-                       CommandHandler('skip', skip_location)],
-
-            BIO: [MessageHandler(Filters.text & ~Filters.command, bio)]
+            PHOTO: [MessageHandler(Filters.photo, photo), CommandHandler('skip', skip_photo)],
+            LOCATION: [
+                MessageHandler(Filters.location, location),
+                CommandHandler('skip', skip_location),
+            ],
+            BIO: [MessageHandler(Filters.text & ~Filters.command, bio)],
         },
-
-        fallbacks=[CommandHandler('cancel', cancel)]
+        fallbacks=[CommandHandler('cancel', cancel)],
     )
 
-    dp.add_handler(conv_handler)
+    dispatcher.add_handler(conv_handler)
 
     # Start the Bot
     updater.start_polling()

examples/conversationbot2.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
+# pylint: disable=W0613, C0116
+# type: ignore[union-attr]
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -15,120 +16,133 @@ bot.
 """
 
 import logging
+from typing import Dict
 
-from telegram import ReplyKeyboardMarkup
-from telegram.ext import (Updater, CommandHandler, MessageHandler, Filters,
-                          ConversationHandler)
+from telegram import ReplyKeyboardMarkup, Update
+from telegram.ext import (
+    Updater,
+    CommandHandler,
+    MessageHandler,
+    Filters,
+    ConversationHandler,
+    CallbackContext,
+)
 
 # Enable logging
-logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-                    level=logging.INFO)
+logging.basicConfig(
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', level=logging.INFO
+)
 
 logger = logging.getLogger(__name__)
 
 CHOOSING, TYPING_REPLY, TYPING_CHOICE = range(3)
 
-reply_keyboard = [['Age', 'Favourite colour'],
-                  ['Number of siblings', 'Something else...'],
-                  ['Done']]
+reply_keyboard = [
+    ['Age', 'Favourite colour'],
+    ['Number of siblings', 'Something else...'],
+    ['Done'],
+]
 markup = ReplyKeyboardMarkup(reply_keyboard, one_time_keyboard=True)
 
 
-def facts_to_str(user_data):
+def facts_to_str(user_data: Dict[str, str]) -> str:
     facts = list()
 
     for key, value in user_data.items():
-        facts.append('{} - {}'.format(key, value))
+        facts.append(f'{key} - {value}')
 
     return "\n".join(facts).join(['\n', '\n'])
 
 
-def start(update, context):
+def start(update: Update, context: CallbackContext) -> int:
     update.message.reply_text(
         "Hi! My name is Doctor Botter. I will hold a more complex conversation with you. "
         "Why don't you tell me something about yourself?",
-        reply_markup=markup)
+        reply_markup=markup,
+    )
 
     return CHOOSING
 
 
-def regular_choice(update, context):
+def regular_choice(update: Update, context: CallbackContext) -> int:
     text = update.message.text
     context.user_data['choice'] = text
-    update.message.reply_text(
-        'Your {}? Yes, I would love to hear about that!'.format(text.lower()))
+    update.message.reply_text(f'Your {text.lower()}? Yes, I would love to hear about that!')
 
     return TYPING_REPLY
 
 
-def custom_choice(update, context):
-    update.message.reply_text('Alright, please send me the category first, '
-                              'for example "Most impressive skill"')
+def custom_choice(update: Update, context: CallbackContext) -> int:
+    update.message.reply_text(
+        'Alright, please send me the category first, ' 'for example "Most impressive skill"'
+    )
 
     return TYPING_CHOICE
 
 
-def received_information(update, context):
+def received_information(update: Update, context: CallbackContext) -> int:
     user_data = context.user_data
     text = update.message.text
     category = user_data['choice']
     user_data[category] = text
     del user_data['choice']
 
-    update.message.reply_text("Neat! Just so you know, this is what you already told me:"
-                              "{} You can tell me more, or change your opinion"
-                              " on something.".format(facts_to_str(user_data)),
-                              reply_markup=markup)
+    update.message.reply_text(
+        "Neat! Just so you know, this is what you already told me:"
+        f"{facts_to_str(user_data)} You can tell me more, or change your opinion"
+        " on something.",
+        reply_markup=markup,
+    )
 
     return CHOOSING
 
 
-def done(update, context):
+def done(update: Update, context: CallbackContext) -> int:
     user_data = context.user_data
     if 'choice' in user_data:
         del user_data['choice']
 
-    update.message.reply_text("I learned these facts about you:"
-                              "{}"
-                              "Until next time!".format(facts_to_str(user_data)))
+    update.message.reply_text(
+        f"I learned these facts about you: {facts_to_str(user_data)} Until next time!"
+    )
 
     user_data.clear()
     return ConversationHandler.END
 
 
-def main():
+def main() -> None:
     # Create the Updater and pass it your bot's token.
-    # Make sure to set use_context=True to use the new context based callbacks
-    # Post version 12 this will no longer be necessary
-    updater = Updater("TOKEN", use_context=True)
+    updater = Updater("TOKEN")
 
     # Get the dispatcher to register handlers
-    dp = updater.dispatcher
+    dispatcher = updater.dispatcher
 
     # Add conversation handler with the states CHOOSING, TYPING_CHOICE and TYPING_REPLY
     conv_handler = ConversationHandler(
         entry_points=[CommandHandler('start', start)],
-
         states={
-            CHOOSING: [MessageHandler(Filters.regex('^(Age|Favourite colour|Number of siblings)$'),
-                                      regular_choice),
-                       MessageHandler(Filters.regex('^Something else...$'),
-                                      custom_choice)
-                       ],
-
+            CHOOSING: [
+                MessageHandler(
+                    Filters.regex('^(Age|Favourite colour|Number of siblings)$'), regular_choice
+                ),
+                MessageHandler(Filters.regex('^Something else...$'), custom_choice),
+            ],
             TYPING_CHOICE: [
-                MessageHandler(Filters.text & ~(Filters.command | Filters.regex('^Done$')),
-                               regular_choice)],
-
+                MessageHandler(
+                    Filters.text & ~(Filters.command | Filters.regex('^Done$')), regular_choice
+                )
+            ],
             TYPING_REPLY: [
-                MessageHandler(Filters.text & ~(Filters.command | Filters.regex('^Done$')),
-                               received_information)],
+                MessageHandler(
+                    Filters.text & ~(Filters.command | Filters.regex('^Done$')),
+                    received_information,
+                )
+            ],
         },
-
-        fallbacks=[MessageHandler(Filters.regex('^Done$'), done)]
+        fallbacks=[MessageHandler(Filters.regex('^Done$'), done)],
     )
 
-    dp.add_handler(conv_handler)
+    dispatcher.add_handler(conv_handler)
 
     # Start the Bot
     updater.start_polling()

examples/deeplinking.py

@@ -1,5 +1,7 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
+# pylint: disable=W0613, C0116
+# type: ignore[union-attr]
+# This program is dedicated to the public domain under the CC0 license.
 
 """Bot that explains Telegram's "Deep Linking Parameters" functionality.
 
@@ -19,84 +21,125 @@ bot.
 
 import logging
 
-from telegram import ParseMode, InlineKeyboardMarkup, InlineKeyboardButton
-from telegram.ext import Updater, CommandHandler, Filters
+from telegram import ParseMode, InlineKeyboardMarkup, InlineKeyboardButton, Update
+from telegram.ext import (
+    Updater,
+    CommandHandler,
+    CallbackQueryHandler,
+    Filters,
+    CallbackContext,
+)
 
 # Enable logging
 from telegram.utils import helpers
 
-logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-                    level=logging.INFO)
+logging.basicConfig(
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", level=logging.INFO
+)
 
 logger = logging.getLogger(__name__)
 
 # Define constants that will allow us to reuse the deep-linking parameters.
-CHECK_THIS_OUT = 'check-this-out'
-USING_ENTITIES = 'using-entities-here'
-SO_COOL = 'so-cool'
+CHECK_THIS_OUT = "check-this-out"
+USING_ENTITIES = "using-entities-here"
+USING_KEYBOARD = "using-keyboard-here"
+SO_COOL = "so-cool"
+
+# Callback data to pass in 3rd level deeplinking
+KEYBOARD_CALLBACKDATA = "keyboard-callback-data"
 
 
-def start(update, context):
+def start(update: Update, context: CallbackContext) -> None:
     """Send a deep-linked URL when the command /start is issued."""
     bot = context.bot
-    url = helpers.create_deep_linked_url(bot.get_me().username, CHECK_THIS_OUT, group=True)
+    url = helpers.create_deep_linked_url(bot.username, CHECK_THIS_OUT, group=True)
     text = "Feel free to tell your friends about it:\n\n" + url
     update.message.reply_text(text)
 
 
-def deep_linked_level_1(update, context):
+def deep_linked_level_1(update: Update, context: CallbackContext) -> None:
     """Reached through the CHECK_THIS_OUT payload"""
     bot = context.bot
-    url = helpers.create_deep_linked_url(bot.get_me().username, SO_COOL)
-    text = "Awesome, you just accessed hidden functionality! " \
-           " Now let's get back to the private chat."
+    url = helpers.create_deep_linked_url(bot.username, SO_COOL)
+    text = (
+        "Awesome, you just accessed hidden functionality! "
+        " Now let's get back to the private chat."
+    )
     keyboard = InlineKeyboardMarkup.from_button(
-        InlineKeyboardButton(text='Continue here!', url=url)
+        InlineKeyboardButton(text="Continue here!", url=url)
     )
     update.message.reply_text(text, reply_markup=keyboard)
 
 
-def deep_linked_level_2(update, context):
+def deep_linked_level_2(update: Update, context: CallbackContext) -> None:
     """Reached through the SO_COOL payload"""
     bot = context.bot
-    url = helpers.create_deep_linked_url(bot.get_me().username, USING_ENTITIES)
-    text = "You can also mask the deep-linked URLs as links: " \
-           "[▶️ CLICK HERE]({}).".format(url)
+    url = helpers.create_deep_linked_url(bot.username, USING_ENTITIES)
+    text = f"You can also mask the deep-linked URLs as links: [▶️ CLICK HERE]({url})."
     update.message.reply_text(text, parse_mode=ParseMode.MARKDOWN, disable_web_page_preview=True)
 
 
-def deep_linked_level_3(update, context):
+def deep_linked_level_3(update: Update, context: CallbackContext) -> None:
     """Reached through the USING_ENTITIES payload"""
+    update.message.reply_text(
+        "It is also possible to make deep-linking using InlineKeyboardButtons.",
+        reply_markup=InlineKeyboardMarkup(
+            [[InlineKeyboardButton(text="Like this!", callback_data=KEYBOARD_CALLBACKDATA)]]
+        ),
+    )
+
+
+def deep_link_level_3_callback(update: Update, context: CallbackContext) -> None:
+    """Answers CallbackQuery with deeplinking url."""
+    bot = context.bot
+    url = helpers.create_deep_linked_url(bot.username, USING_KEYBOARD)
+    update.callback_query.answer(url=url)
+
+
+def deep_linked_level_4(update: Update, context: CallbackContext) -> None:
+    """Reached through the USING_KEYBOARD payload"""
     payload = context.args
-    update.message.reply_text("Congratulations! This is as deep as it gets 👏🏻\n\n"
-                              "The payload was: {}".format(payload))
+    update.message.reply_text(
+        f"Congratulations! This is as deep as it gets 👏🏻\n\nThe payload was: {payload}"
+    )
 
 
 def main():
     """Start the bot."""
     # Create the Updater and pass it your bot's token.
-    updater = Updater("TOKEN", use_context=True)
+    updater = Updater("TOKEN")
 
     # Get the dispatcher to register handlers
-    dp = updater.dispatcher
+    dispatcher = updater.dispatcher
 
     # More info on what deep linking actually is (read this first if it's unclear to you):
     # https://core.telegram.org/bots#deep-linking
 
     # Register a deep-linking handler
-    dp.add_handler(CommandHandler("start", deep_linked_level_1, Filters.regex(CHECK_THIS_OUT)))
+    dispatcher.add_handler(
+        CommandHandler("start", deep_linked_level_1, Filters.regex(CHECK_THIS_OUT))
+    )
 
     # This one works with a textual link instead of an URL
-    dp.add_handler(CommandHandler("start", deep_linked_level_2, Filters.regex(SO_COOL)))
+    dispatcher.add_handler(CommandHandler("start", deep_linked_level_2, Filters.regex(SO_COOL)))
 
     # We can also pass on the deep-linking payload
-    dp.add_handler(CommandHandler("start",
-                                  deep_linked_level_3,
-                                  Filters.regex(USING_ENTITIES),
-                                  pass_args=True))
+    dispatcher.add_handler(
+        CommandHandler("start", deep_linked_level_3, Filters.regex(USING_ENTITIES), pass_args=True)
+    )
+
+    # Possible with inline keyboard buttons aswell
+    dispatcher.add_handler(
+        CommandHandler("start", deep_linked_level_4, Filters.regex(USING_KEYBOARD))
+    )
+
+    # register callback handler for inline keyboard button
+    dispatcher.add_handler(
+        CallbackQueryHandler(deep_link_level_3_callback, pattern=KEYBOARD_CALLBACKDATA)
+    )
 
     # Make sure the deep-linking handlers occur *before* the normal /start handler.
-    dp.add_handler(CommandHandler("start", start))
+    dispatcher.add_handler(CommandHandler("start", start))
 
     # Start the Bot
     updater.start_polling()
@@ -107,5 +150,5 @@ def main():
     updater.idle()
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     main()

examples/echobot.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
+# pylint: disable=W0613, C0116
+# type: ignore[union-attr]
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -17,28 +18,30 @@ bot.
 
 import logging
 
-from telegram.ext import Updater, CommandHandler, MessageHandler, Filters
+from telegram import Update
+from telegram.ext import Updater, CommandHandler, MessageHandler, Filters, CallbackContext
 
 # Enable logging
-logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-                    level=logging.INFO)
+logging.basicConfig(
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', level=logging.INFO
+)
 
 logger = logging.getLogger(__name__)
 
 
 # Define a few command handlers. These usually take the two arguments update and
 # context. Error handlers also receive the raised TelegramError object in error.
-def start(update, context):
+def start(update: Update, context: CallbackContext) -> None:
     """Send a message when the command /start is issued."""
     update.message.reply_text('Hi!')
 
 
-def help_command(update, context):
+def help_command(update: Update, context: CallbackContext) -> None:
     """Send a message when the command /help is issued."""
     update.message.reply_text('Help!')
 
 
-def echo(update, context):
+def echo(update: Update, context: CallbackContext) -> None:
     """Echo the user message."""
     update.message.reply_text(update.message.text)
 
@@ -46,19 +49,17 @@ def echo(update, context):
 def main():
     """Start the bot."""
     # Create the Updater and pass it your bot's token.
-    # Make sure to set use_context=True to use the new context based callbacks
-    # Post version 12 this will no longer be necessary
-    updater = Updater("TOKEN", use_context=True)
+    updater = Updater("TOKEN")
 
     # Get the dispatcher to register handlers
-    dp = updater.dispatcher
+    dispatcher = updater.dispatcher
 
     # on different commands - answer in Telegram
-    dp.add_handler(CommandHandler("start", start))
-    dp.add_handler(CommandHandler("help", help_command))
+    dispatcher.add_handler(CommandHandler("start", start))
+    dispatcher.add_handler(CommandHandler("help", help_command))
 
     # on noncommand i.e message - echo the message on Telegram
-    dp.add_handler(MessageHandler(Filters.text & ~Filters.command, echo))
+    dispatcher.add_handler(MessageHandler(Filters.text & ~Filters.command, echo))
 
     # Start the Bot
     updater.start_polling()

examples/errorhandlerbot.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
+# pylint: disable=W0613, C0116
+# type: ignore[union-attr]
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -13,8 +14,9 @@ import traceback
 from telegram import Update, ParseMode
 from telegram.ext import Updater, CallbackContext, CommandHandler
 
-logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-                    level=logging.INFO)
+logging.basicConfig(
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', level=logging.INFO
+)
 
 logger = logging.getLogger(__name__)
 
@@ -26,7 +28,7 @@ BOT_TOKEN = "TOKEN"
 DEVELOPER_CHAT_ID = 123456789
 
 
-def error_handler(update: Update, context: CallbackContext):
+def error_handler(update: Update, context: CallbackContext) -> None:
     """Log the error and send a telegram message to notify the developer."""
     # Log the error before we do anything else, so we can see it even if something breaks.
     logger.error(msg="Exception while handling an update:", exc_info=context.error)
@@ -34,53 +36,48 @@ def error_handler(update: Update, context: CallbackContext):
     # traceback.format_exception returns the usual python message about an exception, but as a
     # list of strings rather than a single string, so we have to join them together.
     tb_list = traceback.format_exception(None, context.error, context.error.__traceback__)
-    tb = ''.join(tb_list)
+    tb_string = ''.join(tb_list)
 
     # Build the message with some markup and additional information about what happened.
     # You might need to add some logic to deal with messages longer than the 4096 character limit.
     message = (
-        'An exception was raised while handling an update\n'
-        '<pre>update = {}</pre>\n\n'
-        '<pre>context.chat_data = {}</pre>\n\n'
-        '<pre>context.user_data = {}</pre>\n\n'
-        '<pre>{}</pre>'
-    ).format(
-        html.escape(json.dumps(update.to_dict(), indent=2, ensure_ascii=False)),
-        html.escape(str(context.chat_data)),
-        html.escape(str(context.user_data)),
-        html.escape(tb)
+        f'An exception was raised while handling an update\n'
+        f'<pre>update = {html.escape(json.dumps(update.to_dict(), indent=2, ensure_ascii=False))}'
+        '</pre>\n\n'
+        f'<pre>context.chat_data = {html.escape(str(context.chat_data))}</pre>\n\n'
+        f'<pre>context.user_data = {html.escape(str(context.user_data))}</pre>\n\n'
+        f'<pre>{html.escape(tb_string)}</pre>'
     )
 
     # Finally, send the message
     context.bot.send_message(chat_id=DEVELOPER_CHAT_ID, text=message, parse_mode=ParseMode.HTML)
 
 
-def bad_command(update: Update, context: CallbackContext):
+def bad_command(update: Update, context: CallbackContext) -> None:
     """Raise an error to trigger the error handler."""
     context.bot.wrong_method_name()
 
 
-def start(update: Update, context: CallbackContext):
-    update.effective_message.reply_html('Use /bad_command to cause an error.\n'
-                                        'Your chat id is <code>{}</code>.'
-                                        .format(update.effective_chat.id))
+def start(update: Update, context: CallbackContext) -> None:
+    update.effective_message.reply_html(
+        'Use /bad_command to cause an error.\n'
+        f'Your chat id is <code>{update.effective_chat.id}</code>.'
+    )
 
 
 def main():
     # Create the Updater and pass it your bot's token.
-    # Make sure to set use_context=True to use the new context based callbacks
-    # Post version 12 this will no longer be necessary
-    updater = Updater(BOT_TOKEN, use_context=True)
+    updater = Updater(BOT_TOKEN)
 
     # Get the dispatcher to register handlers
-    dp = updater.dispatcher
+    dispatcher = updater.dispatcher
 
     # Register the commands...
-    dp.add_handler(CommandHandler('start', start))
-    dp.add_handler(CommandHandler('bad_command', bad_command))
+    dispatcher.add_handler(CommandHandler('start', start))
+    dispatcher.add_handler(CommandHandler('bad_command', bad_command))
 
     # ...and the error handler
-    dp.add_error_handler(error_handler)
+    dispatcher.add_error_handler(error_handler)
 
     # Start the Bot
     updater.start_polling()

examples/inlinebot.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
+# pylint: disable=W0613, C0116
+# type: ignore[union-attr]
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -15,70 +16,69 @@ bot.
 import logging
 from uuid import uuid4
 
-from telegram import InlineQueryResultArticle, ParseMode, \
-    InputTextMessageContent
-from telegram.ext import Updater, InlineQueryHandler, CommandHandler
+from telegram import InlineQueryResultArticle, ParseMode, InputTextMessageContent, Update
+from telegram.ext import Updater, InlineQueryHandler, CommandHandler, CallbackContext
 from telegram.utils.helpers import escape_markdown
 
 # Enable logging
-logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-                    level=logging.INFO)
+logging.basicConfig(
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', level=logging.INFO
+)
 
 logger = logging.getLogger(__name__)
 
 
 # Define a few command handlers. These usually take the two arguments update and
 # context. Error handlers also receive the raised TelegramError object in error.
-def start(update, context):
+def start(update: Update, context: CallbackContext) -> None:
     """Send a message when the command /start is issued."""
     update.message.reply_text('Hi!')
 
 
-def help_command(update, context):
+def help_command(update: Update, context: CallbackContext) -> None:
     """Send a message when the command /help is issued."""
     update.message.reply_text('Help!')
 
 
-def inlinequery(update, context):
+def inlinequery(update: Update, context: CallbackContext) -> None:
     """Handle the inline query."""
     query = update.inline_query.query
     results = [
         InlineQueryResultArticle(
-            id=uuid4(),
-            title="Caps",
-            input_message_content=InputTextMessageContent(
-                query.upper())),
+            id=uuid4(), title="Caps", input_message_content=InputTextMessageContent(query.upper())
+        ),
         InlineQueryResultArticle(
             id=uuid4(),
             title="Bold",
             input_message_content=InputTextMessageContent(
-                "*{}*".format(escape_markdown(query)),
-                parse_mode=ParseMode.MARKDOWN)),
+                f"*{escape_markdown(query)}*", parse_mode=ParseMode.MARKDOWN
+            ),
+        ),
         InlineQueryResultArticle(
             id=uuid4(),
             title="Italic",
             input_message_content=InputTextMessageContent(
-                "_{}_".format(escape_markdown(query)),
-                parse_mode=ParseMode.MARKDOWN))]
+                f"_{escape_markdown(query)}_", parse_mode=ParseMode.MARKDOWN
+            ),
+        ),
+    ]
 
     update.inline_query.answer(results)
 
 
-def main():
+def main() -> None:
     # Create the Updater and pass it your bot's token.
-    # Make sure to set use_context=True to use the new context based callbacks
-    # Post version 12 this will no longer be necessary
-    updater = Updater("TOKEN", use_context=True)
+    updater = Updater("TOKEN")
 
     # Get the dispatcher to register handlers
-    dp = updater.dispatcher
+    dispatcher = updater.dispatcher
 
     # on different commands - answer in Telegram
-    dp.add_handler(CommandHandler("start", start))
-    dp.add_handler(CommandHandler("help", help_command))
+    dispatcher.add_handler(CommandHandler("start", start))
+    dispatcher.add_handler(CommandHandler("help", help_command))
 
     # on noncommand i.e message - echo the message on Telegram
-    dp.add_handler(InlineQueryHandler(inlinequery))
+    dispatcher.add_handler(InlineQueryHandler(inlinequery))
 
     # Start the Bot
     updater.start_polling()

examples/inlinekeyboard.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
+# pylint: disable=W0613, C0116
+# type: ignore[union-attr]
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -7,44 +8,46 @@ Basic example for a bot that uses inline keyboards.
 """
 import logging
 
-from telegram import InlineKeyboardButton, InlineKeyboardMarkup
-from telegram.ext import Updater, CommandHandler, CallbackQueryHandler
+from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
+from telegram.ext import Updater, CommandHandler, CallbackQueryHandler, CallbackContext
 
-logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-                    level=logging.INFO)
+logging.basicConfig(
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', level=logging.INFO
+)
 logger = logging.getLogger(__name__)
 
 
-def start(update, context):
-    keyboard = [[InlineKeyboardButton("Option 1", callback_data='1'),
-                 InlineKeyboardButton("Option 2", callback_data='2')],
-
-                [InlineKeyboardButton("Option 3", callback_data='3')]]
+def start(update: Update, context: CallbackContext) -> None:
+    keyboard = [
+        [
+            InlineKeyboardButton("Option 1", callback_data='1'),
+            InlineKeyboardButton("Option 2", callback_data='2'),
+        ],
+        [InlineKeyboardButton("Option 3", callback_data='3')],
+    ]
 
     reply_markup = InlineKeyboardMarkup(keyboard)
 
     update.message.reply_text('Please choose:', reply_markup=reply_markup)
 
 
-def button(update, context):
+def button(update: Update, context: CallbackContext) -> None:
     query = update.callback_query
 
     # CallbackQueries need to be answered, even if no notification to the user is needed
     # Some clients may have trouble otherwise. See https://core.telegram.org/bots/api#callbackquery
     query.answer()
 
-    query.edit_message_text(text="Selected option: {}".format(query.data))
+    query.edit_message_text(text=f"Selected option: {query.data}")
 
 
-def help_command(update, context):
+def help_command(update: Update, context: CallbackContext) -> None:
     update.message.reply_text("Use /start to test this bot.")
 
 
 def main():
     # Create the Updater and pass it your bot's token.
-    # Make sure to set use_context=True to use the new context based callbacks
-    # Post version 12 this will no longer be necessary
-    updater = Updater("TOKEN", use_context=True)
+    updater = Updater("TOKEN")
 
     updater.dispatcher.add_handler(CommandHandler('start', start))
     updater.dispatcher.add_handler(CallbackQueryHandler(button))

examples/inlinekeyboard2.py

@@ -1,5 +1,8 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
+# pylint: disable=W0613, C0116
+# type: ignore[union-attr]
+# This program is dedicated to the public domain under the CC0 license.
+
 """Simple inline keyboard bot with multiple CallbackQueryHandlers.
 
 This Bot uses the Updater class to handle the bot.
@@ -12,13 +15,20 @@ ConversationHandler.
 Send /start to initiate the conversation.
 Press Ctrl-C on the command line to stop the bot.
 """
-from telegram import InlineKeyboardButton, InlineKeyboardMarkup
-from telegram.ext import Updater, CommandHandler, CallbackQueryHandler, ConversationHandler
 import logging
+from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
+from telegram.ext import (
+    Updater,
+    CommandHandler,
+    CallbackQueryHandler,
+    ConversationHandler,
+    CallbackContext,
+)
 
 # Enable logging
-logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-                    level=logging.INFO)
+logging.basicConfig(
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', level=logging.INFO
+)
 
 logger = logging.getLogger(__name__)
 
@@ -28,7 +38,7 @@ FIRST, SECOND = range(2)
 ONE, TWO, THREE, FOUR = range(4)
 
 
-def start(update, context):
+def start(update: Update, context: CallbackContext) -> None:
     """Send message on `/start`."""
     # Get user that sent /start and log his name
     user = update.message.from_user
@@ -38,20 +48,19 @@ def start(update, context):
     # The keyboard is a list of button rows, where each row is in turn
     # a list (hence `[[...]]`).
     keyboard = [
-        [InlineKeyboardButton("1", callback_data=str(ONE)),
-         InlineKeyboardButton("2", callback_data=str(TWO))]
+        [
+            InlineKeyboardButton("1", callback_data=str(ONE)),
+            InlineKeyboardButton("2", callback_data=str(TWO)),
+        ]
     ]
     reply_markup = InlineKeyboardMarkup(keyboard)
     # Send message with text and appended InlineKeyboard
-    update.message.reply_text(
-        "Start handler, Choose a route",
-        reply_markup=reply_markup
-    )
+    update.message.reply_text("Start handler, Choose a route", reply_markup=reply_markup)
     # Tell ConversationHandler that we're in state `FIRST` now
     return FIRST
 
 
-def start_over(update, context):
+def start_over(update: Update, context: CallbackContext) -> None:
     """Prompt same text & keyboard as `start` does but not as new message"""
     # Get CallbackQuery from Update
     query = update.callback_query
@@ -59,102 +68,103 @@ def start_over(update, context):
     # Some clients may have trouble otherwise. See https://core.telegram.org/bots/api#callbackquery
     query.answer()
     keyboard = [
-        [InlineKeyboardButton("1", callback_data=str(ONE)),
-         InlineKeyboardButton("2", callback_data=str(TWO))]
+        [
+            InlineKeyboardButton("1", callback_data=str(ONE)),
+            InlineKeyboardButton("2", callback_data=str(TWO)),
+        ]
     ]
     reply_markup = InlineKeyboardMarkup(keyboard)
     # Instead of sending a new message, edit the message that
     # originated the CallbackQuery. This gives the feeling of an
     # interactive menu.
-    query.edit_message_text(
-        text="Start handler, Choose a route",
-        reply_markup=reply_markup
-    )
+    query.edit_message_text(text="Start handler, Choose a route", reply_markup=reply_markup)
     return FIRST
 
 
-def one(update, context):
+def one(update: Update, context: CallbackContext) -> None:
     """Show new choice of buttons"""
     query = update.callback_query
     query.answer()
     keyboard = [
-        [InlineKeyboardButton("3", callback_data=str(THREE)),
-         InlineKeyboardButton("4", callback_data=str(FOUR))]
+        [
+            InlineKeyboardButton("3", callback_data=str(THREE)),
+            InlineKeyboardButton("4", callback_data=str(FOUR)),
+        ]
     ]
     reply_markup = InlineKeyboardMarkup(keyboard)
     query.edit_message_text(
-        text="First CallbackQueryHandler, Choose a route",
-        reply_markup=reply_markup
+        text="First CallbackQueryHandler, Choose a route", reply_markup=reply_markup
     )
     return FIRST
 
 
-def two(update, context):
+def two(update: Update, context: CallbackContext) -> None:
     """Show new choice of buttons"""
     query = update.callback_query
     query.answer()
     keyboard = [
-        [InlineKeyboardButton("1", callback_data=str(ONE)),
-         InlineKeyboardButton("3", callback_data=str(THREE))]
+        [
+            InlineKeyboardButton("1", callback_data=str(ONE)),
+            InlineKeyboardButton("3", callback_data=str(THREE)),
+        ]
     ]
     reply_markup = InlineKeyboardMarkup(keyboard)
     query.edit_message_text(
-        text="Second CallbackQueryHandler, Choose a route",
-        reply_markup=reply_markup
+        text="Second CallbackQueryHandler, Choose a route", reply_markup=reply_markup
     )
     return FIRST
 
 
-def three(update, context):
+def three(update: Update, context: CallbackContext) -> None:
     """Show new choice of buttons"""
     query = update.callback_query
     query.answer()
     keyboard = [
-        [InlineKeyboardButton("Yes, let's do it again!", callback_data=str(ONE)),
-         InlineKeyboardButton("Nah, I've had enough ...", callback_data=str(TWO))]
+        [
+            InlineKeyboardButton("Yes, let's do it again!", callback_data=str(ONE)),
+            InlineKeyboardButton("Nah, I've had enough ...", callback_data=str(TWO)),
+        ]
     ]
     reply_markup = InlineKeyboardMarkup(keyboard)
     query.edit_message_text(
-        text="Third CallbackQueryHandler. Do want to start over?",
-        reply_markup=reply_markup
+        text="Third CallbackQueryHandler. Do want to start over?", reply_markup=reply_markup
     )
     # Transfer to conversation state `SECOND`
     return SECOND
 
 
-def four(update, context):
+def four(update: Update, context: CallbackContext) -> None:
     """Show new choice of buttons"""
     query = update.callback_query
     query.answer()
     keyboard = [
-        [InlineKeyboardButton("2", callback_data=str(TWO)),
-         InlineKeyboardButton("4", callback_data=str(FOUR))]
+        [
+            InlineKeyboardButton("2", callback_data=str(TWO)),
+            InlineKeyboardButton("4", callback_data=str(FOUR)),
+        ]
     ]
     reply_markup = InlineKeyboardMarkup(keyboard)
     query.edit_message_text(
-        text="Fourth CallbackQueryHandler, Choose a route",
-        reply_markup=reply_markup
+        text="Fourth CallbackQueryHandler, Choose a route", reply_markup=reply_markup
     )
     return FIRST
 
 
-def end(update, context):
+def end(update: Update, context: CallbackContext) -> None:
     """Returns `ConversationHandler.END`, which tells the
     ConversationHandler that the conversation is over"""
     query = update.callback_query
     query.answer()
-    query.edit_message_text(
-        text="See you next time!"
-    )
+    query.edit_message_text(text="See you next time!")
     return ConversationHandler.END
 
 
 def main():
     # Create the Updater and pass it your bot's token.
-    updater = Updater("TOKEN", use_context=True)
+    updater = Updater("TOKEN")
 
     # Get the dispatcher to register handlers
-    dp = updater.dispatcher
+    dispatcher = updater.dispatcher
 
     # Setup conversation handler with the states FIRST and SECOND
     # Use the pattern parameter to pass CallbackQueries with specific
@@ -165,19 +175,23 @@ def main():
     conv_handler = ConversationHandler(
         entry_points=[CommandHandler('start', start)],
         states={
-            FIRST: [CallbackQueryHandler(one, pattern='^' + str(ONE) + '$'),
-                    CallbackQueryHandler(two, pattern='^' + str(TWO) + '$'),
-                    CallbackQueryHandler(three, pattern='^' + str(THREE) + '$'),
-                    CallbackQueryHandler(four, pattern='^' + str(FOUR) + '$')],
-            SECOND: [CallbackQueryHandler(start_over, pattern='^' + str(ONE) + '$'),
-                     CallbackQueryHandler(end, pattern='^' + str(TWO) + '$')]
+            FIRST: [
+                CallbackQueryHandler(one, pattern='^' + str(ONE) + '$'),
+                CallbackQueryHandler(two, pattern='^' + str(TWO) + '$'),
+                CallbackQueryHandler(three, pattern='^' + str(THREE) + '$'),
+                CallbackQueryHandler(four, pattern='^' + str(FOUR) + '$'),
+            ],
+            SECOND: [
+                CallbackQueryHandler(start_over, pattern='^' + str(ONE) + '$'),
+                CallbackQueryHandler(end, pattern='^' + str(TWO) + '$'),
+            ],
         },
-        fallbacks=[CommandHandler('start', start)]
+        fallbacks=[CommandHandler('start', start)],
     )
 
     # Add ConversationHandler to dispatcher that will be used for handling
     # updates
-    dp.add_handler(conv_handler)
+    dispatcher.add_handler(conv_handler)
 
     # Start the Bot
     updater.start_polling()

examples/nestedconversationbot.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
+# pylint: disable=W0613, C0116
+# type: ignore[union-attr]
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -16,13 +17,21 @@ bot.
 
 import logging
 
-from telegram import (InlineKeyboardMarkup, InlineKeyboardButton)
-from telegram.ext import (Updater, CommandHandler, MessageHandler, Filters,
-                          ConversationHandler, CallbackQueryHandler)
+from telegram import InlineKeyboardMarkup, InlineKeyboardButton, Update
+from telegram.ext import (
+    Updater,
+    CommandHandler,
+    MessageHandler,
+    Filters,
+    ConversationHandler,
+    CallbackQueryHandler,
+    CallbackContext,
+)
 
 # Enable logging
-logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-                    level=logging.INFO)
+logging.basicConfig(
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', level=logging.INFO
+)
 
 logger = logging.getLogger(__name__)
 
@@ -38,30 +47,46 @@ STOPPING, SHOWING = map(chr, range(8, 10))
 END = ConversationHandler.END
 
 # Different constants for this example
-(PARENTS, CHILDREN, SELF, GENDER, MALE, FEMALE, AGE, NAME, START_OVER, FEATURES,
- CURRENT_FEATURE, CURRENT_LEVEL) = map(chr, range(10, 22))
+(
+    PARENTS,
+    CHILDREN,
+    SELF,
+    GENDER,
+    MALE,
+    FEMALE,
+    AGE,
+    NAME,
+    START_OVER,
+    FEATURES,
+    CURRENT_FEATURE,
+    CURRENT_LEVEL,
+) = map(chr, range(10, 22))
 
 
 # Helper
 def _name_switcher(level):
     if level == PARENTS:
-        return ('Father', 'Mother')
-    elif level == CHILDREN:
-        return ('Brother', 'Sister')
+        return 'Father', 'Mother'
+    return 'Brother', 'Sister'
 
 
 # Top level conversation callbacks
-def start(update, context):
+def start(update: Update, context: CallbackContext) -> None:
     """Select an action: Adding parent/child or show data."""
-    text = 'You may add a familiy member, yourself show the gathered data or end the ' \
-           'conversation. To abort, simply type /stop.'
-    buttons = [[
-        InlineKeyboardButton(text='Add family member', callback_data=str(ADDING_MEMBER)),
-        InlineKeyboardButton(text='Add yourself', callback_data=str(ADDING_SELF))
-    ], [
-        InlineKeyboardButton(text='Show data', callback_data=str(SHOWING)),
-        InlineKeyboardButton(text='Done', callback_data=str(END))
-    ]]
+    text = (
+        'You may add a familiy member, yourself show the gathered data or end the '
+        'conversation. To abort, simply type /stop.'
+    )
+    buttons = [
+        [
+            InlineKeyboardButton(text='Add family member', callback_data=str(ADDING_MEMBER)),
+            InlineKeyboardButton(text='Add yourself', callback_data=str(ADDING_SELF)),
+        ],
+        [
+            InlineKeyboardButton(text='Show data', callback_data=str(SHOWING)),
+            InlineKeyboardButton(text='Done', callback_data=str(END)),
+        ],
+    ]
     keyboard = InlineKeyboardMarkup(buttons)
 
     # If we're starting over we don't need do send a new message
@@ -69,15 +94,16 @@ def start(update, context):
         update.callback_query.answer()
         update.callback_query.edit_message_text(text=text, reply_markup=keyboard)
     else:
-        update.message.reply_text('Hi, I\'m FamiliyBot and here to help you gather information'
-                                  'about your family.')
+        update.message.reply_text(
+            'Hi, I\'m FamiliyBot and here to help you gather information' 'about your family.'
+        )
         update.message.reply_text(text=text, reply_markup=keyboard)
 
     context.user_data[START_OVER] = False
     return SELECTING_ACTION
 
 
-def adding_self(update, context):
+def adding_self(update: Update, context: CallbackContext) -> None:
     """Add information about youself."""
     context.user_data[CURRENT_LEVEL] = SELF
     text = 'Okay, please tell me about yourself.'
@@ -90,8 +116,9 @@ def adding_self(update, context):
     return DESCRIBING_SELF
 
 
-def show_data(update, context):
+def show_data(update: Update, context: CallbackContext) -> None:
     """Pretty print gathered data."""
+
     def prettyprint(user_data, level):
         people = user_data.get(level)
         if not people:
@@ -100,41 +127,38 @@ def show_data(update, context):
         text = ''
         if level == SELF:
             for person in user_data[level]:
-                text += '\nName: {}, Age: {}'.format(person.get(NAME, '-'), person.get(AGE, '-'))
+                text += f"\nName: {person.get(NAME, '-')}, Age: {person.get(AGE, '-')}"
         else:
             male, female = _name_switcher(level)
 
             for person in user_data[level]:
                 gender = female if person[GENDER] == FEMALE else male
-                text += '\n{}: Name: {}, Age: {}'.format(gender, person.get(NAME, '-'),
-                                                         person.get(AGE, '-'))
+                text += f"\n{gender}: Name: {person.get(NAME, '-')}, Age: {person.get(AGE, '-')}"
         return text
 
-    ud = context.user_data
-    text = 'Yourself:' + prettyprint(ud, SELF)
-    text += '\n\nParents:' + prettyprint(ud, PARENTS)
-    text += '\n\nChildren:' + prettyprint(ud, CHILDREN)
+    user_data = context.user_data
+    text = 'Yourself:' + prettyprint(user_data, SELF)
+    text += '\n\nParents:' + prettyprint(user_data, PARENTS)
+    text += '\n\nChildren:' + prettyprint(user_data, CHILDREN)
 
-    buttons = [[
-        InlineKeyboardButton(text='Back', callback_data=str(END))
-    ]]
+    buttons = [[InlineKeyboardButton(text='Back', callback_data=str(END))]]
     keyboard = InlineKeyboardMarkup(buttons)
 
     update.callback_query.answer()
     update.callback_query.edit_message_text(text=text, reply_markup=keyboard)
-    ud[START_OVER] = True
+    user_data[START_OVER] = True
 
     return SHOWING
 
 
-def stop(update, context):
+def stop(update: Update, context: CallbackContext) -> None:
     """End Conversation by command."""
     update.message.reply_text('Okay, bye.')
 
     return END
 
 
-def end(update, context):
+def end(update: Update, context: CallbackContext) -> None:
     """End conversation from InlineKeyboardButton."""
     update.callback_query.answer()
 
@@ -145,16 +169,19 @@ def end(update, context):
 
 
 # Second level conversation callbacks
-def select_level(update, context):
+def select_level(update: Update, context: CallbackContext) -> None:
     """Choose to add a parent or a child."""
     text = 'You may add a parent or a child. Also you can show the gathered data or go back.'
-    buttons = [[
-        InlineKeyboardButton(text='Add parent', callback_data=str(PARENTS)),
-        InlineKeyboardButton(text='Add child', callback_data=str(CHILDREN))
-    ], [
-        InlineKeyboardButton(text='Show data', callback_data=str(SHOWING)),
-        InlineKeyboardButton(text='Back', callback_data=str(END))
-    ]]
+    buttons = [
+        [
+            InlineKeyboardButton(text='Add parent', callback_data=str(PARENTS)),
+            InlineKeyboardButton(text='Add child', callback_data=str(CHILDREN)),
+        ],
+        [
+            InlineKeyboardButton(text='Show data', callback_data=str(SHOWING)),
+            InlineKeyboardButton(text='Back', callback_data=str(END)),
+        ],
+    ]
     keyboard = InlineKeyboardMarkup(buttons)
 
     update.callback_query.answer()
@@ -163,7 +190,7 @@ def select_level(update, context):
     return SELECTING_LEVEL
 
 
-def select_gender(update, context):
+def select_gender(update: Update, context: CallbackContext) -> None:
     """Choose to add mother or father."""
     level = update.callback_query.data
     context.user_data[CURRENT_LEVEL] = level
@@ -172,13 +199,16 @@ def select_gender(update, context):
 
     male, female = _name_switcher(level)
 
-    buttons = [[
-        InlineKeyboardButton(text='Add ' + male, callback_data=str(MALE)),
-        InlineKeyboardButton(text='Add ' + female, callback_data=str(FEMALE))
-    ], [
-        InlineKeyboardButton(text='Show data', callback_data=str(SHOWING)),
-        InlineKeyboardButton(text='Back', callback_data=str(END))
-    ]]
+    buttons = [
+        [
+            InlineKeyboardButton(text='Add ' + male, callback_data=str(MALE)),
+            InlineKeyboardButton(text='Add ' + female, callback_data=str(FEMALE)),
+        ],
+        [
+            InlineKeyboardButton(text='Show data', callback_data=str(SHOWING)),
+            InlineKeyboardButton(text='Back', callback_data=str(END)),
+        ],
+    ]
     keyboard = InlineKeyboardMarkup(buttons)
 
     update.callback_query.answer()
@@ -187,7 +217,7 @@ def select_gender(update, context):
     return SELECTING_GENDER
 
 
-def end_second_level(update, context):
+def end_second_level(update: Update, context: CallbackContext) -> None:
     """Return to top level conversation."""
     context.user_data[START_OVER] = True
     start(update, context)
@@ -196,13 +226,15 @@ def end_second_level(update, context):
 
 
 # Third level callbacks
-def select_feature(update, context):
+def select_feature(update: Update, context: CallbackContext) -> None:
     """Select a feature to update for the person."""
-    buttons = [[
-        InlineKeyboardButton(text='Name', callback_data=str(NAME)),
-        InlineKeyboardButton(text='Age', callback_data=str(AGE)),
-        InlineKeyboardButton(text='Done', callback_data=str(END)),
-    ]]
+    buttons = [
+        [
+            InlineKeyboardButton(text='Name', callback_data=str(NAME)),
+            InlineKeyboardButton(text='Age', callback_data=str(AGE)),
+            InlineKeyboardButton(text='Done', callback_data=str(END)),
+        ]
+    ]
     keyboard = InlineKeyboardMarkup(buttons)
 
     # If we collect features for a new person, clear the cache and save the gender
@@ -221,7 +253,7 @@ def select_feature(update, context):
     return SELECTING_FEATURE
 
 
-def ask_for_input(update, context):
+def ask_for_input(update: Update, context: CallbackContext) -> None:
     """Prompt user to input data for selected feature."""
     context.user_data[CURRENT_FEATURE] = update.callback_query.data
     text = 'Okay, tell me.'
@@ -232,27 +264,27 @@ def ask_for_input(update, context):
     return TYPING
 
 
-def save_input(update, context):
+def save_input(update: Update, context: CallbackContext) -> None:
     """Save input for feature and return to feature selection."""
-    ud = context.user_data
-    ud[FEATURES][ud[CURRENT_FEATURE]] = update.message.text
+    user_data = context.user_data
+    user_data[FEATURES][user_data[CURRENT_FEATURE]] = update.message.text
 
-    ud[START_OVER] = True
+    user_data[START_OVER] = True
 
     return select_feature(update, context)
 
 
-def end_describing(update, context):
+def end_describing(update: Update, context: CallbackContext) -> None:
     """End gathering of features and return to parent conversation."""
-    ud = context.user_data
-    level = ud[CURRENT_LEVEL]
-    if not ud.get(level):
-        ud[level] = []
-    ud[level].append(ud[FEATURES])
+    user_data = context.user_data
+    level = user_data[CURRENT_LEVEL]
+    if not user_data.get(level):
+        user_data[level] = []
+    user_data[level].append(user_data[FEATURES])
 
     # Print upper level menu
     if level == SELF:
-        ud[START_OVER] = True
+        user_data[START_OVER] = True
         start(update, context)
     else:
         select_level(update, context)
@@ -260,7 +292,7 @@ def end_describing(update, context):
     return END
 
 
-def stop_nested(update, context):
+def stop_nested(update: Update, context: CallbackContext) -> None:
     """Completely end conversation from within nested conversation."""
     update.message.reply_text('Okay, bye.')
 
@@ -269,55 +301,50 @@ def stop_nested(update, context):
 
 def main():
     # Create the Updater and pass it your bot's token.
-    # Make sure to set use_context=True to use the new context based callbacks
-    # Post version 12 this will no longer be necessary
-    updater = Updater("TOKEN", use_context=True)
+    updater = Updater("TOKEN")
 
     # Get the dispatcher to register handlers
-    dp = updater.dispatcher
+    dispatcher = updater.dispatcher
 
     # Set up third level ConversationHandler (collecting features)
     description_conv = ConversationHandler(
-        entry_points=[CallbackQueryHandler(select_feature,
-                                           pattern='^' + str(MALE) + '$|^' + str(FEMALE) + '$')],
-
+        entry_points=[
+            CallbackQueryHandler(
+                select_feature, pattern='^' + str(MALE) + '$|^' + str(FEMALE) + '$'
+            )
+        ],
         states={
-            SELECTING_FEATURE: [CallbackQueryHandler(ask_for_input,
-                                                     pattern='^(?!' + str(END) + ').*$')],
+            SELECTING_FEATURE: [
+                CallbackQueryHandler(ask_for_input, pattern='^(?!' + str(END) + ').*$')
+            ],
             TYPING: [MessageHandler(Filters.text & ~Filters.command, save_input)],
         },
-
         fallbacks=[
             CallbackQueryHandler(end_describing, pattern='^' + str(END) + '$'),
-            CommandHandler('stop', stop_nested)
+            CommandHandler('stop', stop_nested),
         ],
-
         map_to_parent={
             # Return to second level menu
             END: SELECTING_LEVEL,
             # End conversation alltogether
             STOPPING: STOPPING,
-        }
+        },
     )
 
     # Set up second level ConversationHandler (adding a person)
     add_member_conv = ConversationHandler(
-        entry_points=[CallbackQueryHandler(select_level,
-                                           pattern='^' + str(ADDING_MEMBER) + '$')],
-
+        entry_points=[CallbackQueryHandler(select_level, pattern='^' + str(ADDING_MEMBER) + '$')],
         states={
-            SELECTING_LEVEL: [CallbackQueryHandler(select_gender,
-                                                   pattern='^{}$|^{}$'.format(str(PARENTS),
-                                                                              str(CHILDREN)))],
-            SELECTING_GENDER: [description_conv]
+            SELECTING_LEVEL: [
+                CallbackQueryHandler(select_gender, pattern=f'^{PARENTS}$|^{CHILDREN}$')
+            ],
+            SELECTING_GENDER: [description_conv],
         },
-
         fallbacks=[
             CallbackQueryHandler(show_data, pattern='^' + str(SHOWING) + '$'),
             CallbackQueryHandler(end_second_level, pattern='^' + str(END) + '$'),
-            CommandHandler('stop', stop_nested)
+            CommandHandler('stop', stop_nested),
         ],
-
         map_to_parent={
             # After showing data return to top level menu
             SHOWING: SHOWING,
@@ -325,7 +352,7 @@ def main():
             END: SELECTING_ACTION,
             # End conversation alltogether
             STOPPING: END,
-        }
+        },
     )
 
     # Set up top level ConversationHandler (selecting action)
@@ -339,7 +366,6 @@ def main():
     ]
     conv_handler = ConversationHandler(
         entry_points=[CommandHandler('start', start)],
-
         states={
             SHOWING: [CallbackQueryHandler(start, pattern='^' + str(END) + '$')],
             SELECTING_ACTION: selection_handlers,
@@ -347,11 +373,10 @@ def main():
             DESCRIBING_SELF: [description_conv],
             STOPPING: [CommandHandler('start', start)],
         },
-
         fallbacks=[CommandHandler('stop', stop)],
     )
 
-    dp.add_handler(conv_handler)
+    dispatcher.add_handler(conv_handler)
 
     # Start the Bot
     updater.start_polling()

examples/passportbot.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
+# pylint: disable=W0613, C0116
+# type: ignore[union-attr]
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -12,16 +13,18 @@ See https://git.io/fAvYd for how to use Telegram Passport properly with python-t
 """
 import logging
 
-from telegram.ext import Updater, MessageHandler, Filters
+from telegram import Update
+from telegram.ext import Updater, MessageHandler, Filters, CallbackContext
 
 # Enable logging
-logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-                    level=logging.DEBUG)
+logging.basicConfig(
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', level=logging.DEBUG
+)
 
 logger = logging.getLogger(__name__)
 
 
-def msg(update, context):
+def msg(update: Update, context: CallbackContext) -> None:
     # If we received any passport data
     passport_data = update.message.passport_data
     if passport_data:
@@ -39,18 +42,28 @@ def msg(update, context):
                 print('Phone: ', data.phone_number)
             elif data.type == 'email':
                 print('Email: ', data.email)
-            if data.type in ('personal_details', 'passport', 'driver_license', 'identity_card',
-                             'internal_passport', 'address'):
+            if data.type in (
+                'personal_details',
+                'passport',
+                'driver_license',
+                'identity_card',
+                'internal_passport',
+                'address',
+            ):
                 print(data.type, data.data)
-            if data.type in ('utility_bill', 'bank_statement', 'rental_agreement',
-                             'passport_registration', 'temporary_registration'):
+            if data.type in (
+                'utility_bill',
+                'bank_statement',
+                'rental_agreement',
+                'passport_registration',
+                'temporary_registration',
+            ):
                 print(data.type, len(data.files), 'files')
                 for file in data.files:
                     actual_file = file.get_file()
                     print(actual_file)
                     actual_file.download()
-            if data.type in ('passport', 'driver_license', 'identity_card',
-                             'internal_passport'):
+            if data.type in ('passport', 'driver_license', 'identity_card', 'internal_passport'):
                 if data.front_side:
                     file = data.front_side.get_file()
                     print(data.type, file)
@@ -60,16 +73,22 @@ def msg(update, context):
                     file = data.reverse_side.get_file()
                     print(data.type, file)
                     file.download()
-            if data.type in ('passport', 'driver_license', 'identity_card',
-                             'internal_passport'):
+            if data.type in ('passport', 'driver_license', 'identity_card', 'internal_passport'):
                 if data.selfie:
                     file = data.selfie.get_file()
                     print(data.type, file)
                     file.download()
-            if data.type in ('passport', 'driver_license', 'identity_card',
-                             'internal_passport', 'utility_bill', 'bank_statement',
-                             'rental_agreement', 'passport_registration',
-                             'temporary_registration'):
+            if data.type in (
+                'passport',
+                'driver_license',
+                'identity_card',
+                'internal_passport',
+                'utility_bill',
+                'bank_statement',
+                'rental_agreement',
+                'passport_registration',
+                'temporary_registration',
+            ):
                 print(data.type, len(data.translation), 'translation')
                 for file in data.translation:
                     actual_file = file.get_file()
@@ -83,10 +102,10 @@ def main():
     updater = Updater("TOKEN", private_key=open('private.key', 'rb').read())
 
     # Get the dispatcher to register handlers
-    dp = updater.dispatcher
+    dispatcher = updater.dispatcher
 
     # On messages that include passport data call msg
-    dp.add_handler(MessageHandler(Filters.passport_data, msg))
+    dispatcher.add_handler(MessageHandler(Filters.passport_data, msg))
 
     # Start the Bot
     updater.start_polling()

examples/paymentbot.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
+# pylint: disable=W0613, C0116
+# type: ignore[union-attr]
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -8,24 +9,32 @@ Basic example for a bot that can receive payment from user.
 
 import logging
 
-from telegram import (LabeledPrice, ShippingOption)
-from telegram.ext import (Updater, CommandHandler, MessageHandler,
-                          Filters, PreCheckoutQueryHandler, ShippingQueryHandler)
+from telegram import LabeledPrice, ShippingOption, Update
+from telegram.ext import (
+    Updater,
+    CommandHandler,
+    MessageHandler,
+    Filters,
+    PreCheckoutQueryHandler,
+    ShippingQueryHandler,
+    CallbackContext,
+)
 
 # Enable logging
-logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-                    level=logging.INFO)
+logging.basicConfig(
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', level=logging.INFO
+)
 
 logger = logging.getLogger(__name__)
 
 
-def start_callback(update, context):
+def start_callback(update: Update, context: CallbackContext) -> None:
     msg = "Use /shipping to get an invoice for shipping-payment, "
     msg += "or /noshipping for an invoice without shipping."
     update.message.reply_text(msg)
 
 
-def start_with_shipping_callback(update, context):
+def start_with_shipping_callback(update: Update, context: CallbackContext) -> None:
     chat_id = update.message.chat_id
     title = "Payment Example"
     description = "Payment Example using python-telegram-bot"
@@ -43,13 +52,24 @@ def start_with_shipping_callback(update, context):
 
     # optionally pass need_name=True, need_phone_number=True,
     # need_email=True, need_shipping_address=True, is_flexible=True
-    context.bot.send_invoice(chat_id, title, description, payload,
-                             provider_token, start_parameter, currency, prices,
-                             need_name=True, need_phone_number=True,
-                             need_email=True, need_shipping_address=True, is_flexible=True)
+    context.bot.send_invoice(
+        chat_id,
+        title,
+        description,
+        payload,
+        provider_token,
+        start_parameter,
+        currency,
+        prices,
+        need_name=True,
+        need_phone_number=True,
+        need_email=True,
+        need_shipping_address=True,
+        is_flexible=True,
+    )
 
 
-def start_without_shipping_callback(update, context):
+def start_without_shipping_callback(update: Update, context: CallbackContext) -> None:
     chat_id = update.message.chat_id
     title = "Payment Example"
     description = "Payment Example using python-telegram-bot"
@@ -66,29 +86,30 @@ def start_without_shipping_callback(update, context):
 
     # optionally pass need_name=True, need_phone_number=True,
     # need_email=True, need_shipping_address=True, is_flexible=True
-    context.bot.send_invoice(chat_id, title, description, payload,
-                             provider_token, start_parameter, currency, prices)
+    context.bot.send_invoice(
+        chat_id, title, description, payload, provider_token, start_parameter, currency, prices
+    )
 
 
-def shipping_callback(update, context):
+def shipping_callback(update: Update, context: CallbackContext) -> None:
     query = update.shipping_query
     # check the payload, is this from your bot?
     if query.invoice_payload != 'Custom-Payload':
         # answer False pre_checkout_query
         query.answer(ok=False, error_message="Something went wrong...")
         return
-    else:
-        options = list()
-        # a single LabeledPrice
-        options.append(ShippingOption('1', 'Shipping Option A', [LabeledPrice('A', 100)]))
-        # an array of LabeledPrice objects
-        price_list = [LabeledPrice('B1', 150), LabeledPrice('B2', 200)]
-        options.append(ShippingOption('2', 'Shipping Option B', price_list))
-        query.answer(ok=True, shipping_options=options)
+
+    options = list()
+    # a single LabeledPrice
+    options.append(ShippingOption('1', 'Shipping Option A', [LabeledPrice('A', 100)]))
+    # an array of LabeledPrice objects
+    price_list = [LabeledPrice('B1', 150), LabeledPrice('B2', 200)]
+    options.append(ShippingOption('2', 'Shipping Option B', price_list))
+    query.answer(ok=True, shipping_options=options)
 
 
 # after (optional) shipping, it's the pre-checkout
-def precheckout_callback(update, context):
+def precheckout_callback(update: Update, context: CallbackContext) -> None:
     query = update.pre_checkout_query
     # check the payload, is this from your bot?
     if query.invoice_payload != 'Custom-Payload':
@@ -99,35 +120,33 @@ def precheckout_callback(update, context):
 
 
 # finally, after contacting the payment provider...
-def successful_payment_callback(update, context):
+def successful_payment_callback(update: Update, context: CallbackContext) -> None:
     # do something after successfully receiving payment?
     update.message.reply_text("Thank you for your payment!")
 
 
 def main():
     # Create the Updater and pass it your bot's token.
-    # Make sure to set use_context=True to use the new context based callbacks
-    # Post version 12 this will no longer be necessary
-    updater = Updater("TOKEN", use_context=True)
+    updater = Updater("TOKEN")
 
     # Get the dispatcher to register handlers
-    dp = updater.dispatcher
+    dispatcher = updater.dispatcher
 
     # simple start function
-    dp.add_handler(CommandHandler("start", start_callback))
+    dispatcher.add_handler(CommandHandler("start", start_callback))
 
     # Add command handler to start the payment invoice
-    dp.add_handler(CommandHandler("shipping", start_with_shipping_callback))
-    dp.add_handler(CommandHandler("noshipping", start_without_shipping_callback))
+    dispatcher.add_handler(CommandHandler("shipping", start_with_shipping_callback))
+    dispatcher.add_handler(CommandHandler("noshipping", start_without_shipping_callback))
 
     # Optional handler if your product requires shipping
-    dp.add_handler(ShippingQueryHandler(shipping_callback))
+    dispatcher.add_handler(ShippingQueryHandler(shipping_callback))
 
     # Pre-checkout handler to final check
-    dp.add_handler(PreCheckoutQueryHandler(precheckout_callback))
+    dispatcher.add_handler(PreCheckoutQueryHandler(precheckout_callback))
 
     # Success! Notify your user!
-    dp.add_handler(MessageHandler(Filters.successful_payment, successful_payment_callback))
+    dispatcher.add_handler(MessageHandler(Filters.successful_payment, successful_payment_callback))
 
     # Start the Bot
     updater.start_polling()

examples/persistentconversationbot.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
+# pylint: disable=W0613, C0116, C0103
+# type: ignore[union-attr]
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -14,23 +15,34 @@ Press Ctrl-C on the command line or send a signal to the process to stop the
 bot.
 """
 
-from telegram import ReplyKeyboardMarkup
-from telegram.ext import (Updater, CommandHandler, MessageHandler, Filters,
-                          ConversationHandler, PicklePersistence)
-
 import logging
 
+from telegram import ReplyKeyboardMarkup, Update
+from telegram.ext import (
+    Updater,
+    CommandHandler,
+    MessageHandler,
+    Filters,
+    ConversationHandler,
+    PicklePersistence,
+    CallbackContext,
+)
+
+
 # Enable logging
-logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-                    level=logging.INFO)
+logging.basicConfig(
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', level=logging.INFO
+)
 
 logger = logging.getLogger(__name__)
 
 CHOOSING, TYPING_REPLY, TYPING_CHOICE = range(3)
 
-reply_keyboard = [['Age', 'Favourite colour'],
-                  ['Number of siblings', 'Something else...'],
-                  ['Done']]
+reply_keyboard = [
+    ['Age', 'Favourite colour'],
+    ['Number of siblings', 'Something else...'],
+    ['Done'],
+]
 markup = ReplyKeyboardMarkup(reply_keyboard, one_time_keyboard=True)
 
 
@@ -38,79 +50,87 @@ def facts_to_str(user_data):
     facts = list()
 
     for key, value in user_data.items():
-        facts.append('{} - {}'.format(key, value))
+        facts.append(f'{key} - {value}')
 
     return "\n".join(facts).join(['\n', '\n'])
 
 
-def start(update, context):
+def start(update: Update, context: CallbackContext) -> None:
     reply_text = "Hi! My name is Doctor Botter."
     if context.user_data:
-        reply_text += " You already told me your {}. Why don't you tell me something more " \
-                      "about yourself? Or change anything I " \
-                      "already know.".format(", ".join(context.user_data.keys()))
+        reply_text += (
+            f" You already told me your {', '.join(context.user_data.keys())}. Why don't you "
+            f"tell me something more about yourself? Or change anything I already know."
+        )
     else:
-        reply_text += " I will hold a more complex conversation with you. Why don't you tell me " \
-                      "something about yourself?"
+        reply_text += (
+            " I will hold a more complex conversation with you. Why don't you tell me "
+            "something about yourself?"
+        )
     update.message.reply_text(reply_text, reply_markup=markup)
 
     return CHOOSING
 
 
-def regular_choice(update, context):
+def regular_choice(update: Update, context: CallbackContext) -> None:
     text = update.message.text.lower()
     context.user_data['choice'] = text
     if context.user_data.get(text):
-        reply_text = 'Your {}, I already know the following ' \
-                     'about that: {}'.format(text, context.user_data[text])
+        reply_text = (
+            f'Your {text}, I already know the following about that: {context.user_data[text]}'
+        )
     else:
-        reply_text = 'Your {}? Yes, I would love to hear about that!'.format(text)
+        reply_text = f'Your {text}? Yes, I would love to hear about that!'
     update.message.reply_text(reply_text)
 
     return TYPING_REPLY
 
 
-def custom_choice(update, context):
-    update.message.reply_text('Alright, please send me the category first, '
-                              'for example "Most impressive skill"')
+def custom_choice(update: Update, context: CallbackContext) -> None:
+    update.message.reply_text(
+        'Alright, please send me the category first, ' 'for example "Most impressive skill"'
+    )
 
     return TYPING_CHOICE
 
 
-def received_information(update, context):
+def received_information(update: Update, context: CallbackContext) -> None:
     text = update.message.text
     category = context.user_data['choice']
     context.user_data[category] = text.lower()
     del context.user_data['choice']
 
-    update.message.reply_text("Neat! Just so you know, this is what you already told me:"
-                              "{}"
-                              "You can tell me more, or change your opinion on "
-                              "something.".format(facts_to_str(context.user_data)),
-                              reply_markup=markup)
+    update.message.reply_text(
+        "Neat! Just so you know, this is what you already told me:"
+        f"{facts_to_str(context.user_data)}"
+        "You can tell me more, or change your opinion on "
+        "something.",
+        reply_markup=markup,
+    )
 
     return CHOOSING
 
 
-def show_data(update, context):
-    update.message.reply_text("This is what you already told me:"
-                              "{}".format(facts_to_str(context.user_data)))
+def show_data(update: Update, context: CallbackContext) -> None:
+    update.message.reply_text(
+        f"This is what you already told me: {facts_to_str(context.user_data)}"
+    )
 
 
-def done(update, context):
+def done(update: Update, context: CallbackContext) -> None:
     if 'choice' in context.user_data:
         del context.user_data['choice']
 
-    update.message.reply_text("I learned these facts about you:"
-                              "{}"
-                              "Until next time!".format(facts_to_str(context.user_data)))
+    update.message.reply_text(
+        "I learned these facts about you:" f"{facts_to_str(context.user_data)}" "Until next time!"
+    )
     return ConversationHandler.END
 
 
 def main():
     # Create the Updater and pass it your bot's token.
     pp = PicklePersistence(filename='conversationbot')
-    updater = Updater("TOKEN", persistence=pp, use_context=True)
+    updater = Updater("TOKEN", persistence=pp)
 
     # Get the dispatcher to register handlers
     dp = updater.dispatcher
@@ -118,26 +138,28 @@ def main():
     # Add conversation handler with the states CHOOSING, TYPING_CHOICE and TYPING_REPLY
     conv_handler = ConversationHandler(
         entry_points=[CommandHandler('start', start)],
-
         states={
-            CHOOSING: [MessageHandler(Filters.regex('^(Age|Favourite colour|Number of siblings)$'),
-                                      regular_choice),
-                       MessageHandler(Filters.regex('^Something else...$'),
-                                      custom_choice),
-                       ],
-
+            CHOOSING: [
+                MessageHandler(
+                    Filters.regex('^(Age|Favourite colour|Number of siblings)$'), regular_choice
+                ),
+                MessageHandler(Filters.regex('^Something else...$'), custom_choice),
+            ],
             TYPING_CHOICE: [
-                MessageHandler(Filters.text & ~(Filters.command | Filters.regex('^Done$')),
-                               regular_choice)],
-
+                MessageHandler(
+                    Filters.text & ~(Filters.command | Filters.regex('^Done$')), regular_choice
+                )
+            ],
             TYPING_REPLY: [
-                MessageHandler(Filters.text & ~(Filters.command | Filters.regex('^Done$')),
-                               received_information)],
+                MessageHandler(
+                    Filters.text & ~(Filters.command | Filters.regex('^Done$')),
+                    received_information,
+                )
+            ],
         },
-
         fallbacks=[MessageHandler(Filters.regex('^Done$'), done)],
         name="my_conversation",
-        persistent=True
+        persistent=True,
     )
 
     dp.add_handler(conv_handler)

examples/pollbot.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
+# pylint: disable=W0613, C0116
+# type: ignore[union-attr]
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -9,34 +10,62 @@ one the user sends the bot
 """
 import logging
 
-from telegram import (Poll, ParseMode, KeyboardButton, KeyboardButtonPollType,
-                      ReplyKeyboardMarkup, ReplyKeyboardRemove)
-from telegram.ext import (Updater, CommandHandler, PollAnswerHandler, PollHandler, MessageHandler,
-                          Filters)
+from telegram import (
+    Poll,
+    ParseMode,
+    KeyboardButton,
+    KeyboardButtonPollType,
+    ReplyKeyboardMarkup,
+    ReplyKeyboardRemove,
+    Update,
+)
+from telegram.ext import (
+    Updater,
+    CommandHandler,
+    PollAnswerHandler,
+    PollHandler,
+    MessageHandler,
+    Filters,
+    CallbackContext,
+)
 
-logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-                    level=logging.INFO)
+logging.basicConfig(
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', level=logging.INFO
+)
 logger = logging.getLogger(__name__)
 
 
-def start(update, context):
+def start(update: Update, context: CallbackContext) -> None:
     """Inform user about what this bot can do"""
-    update.message.reply_text('Please select /poll to get a Poll, /quiz to get a Quiz or /preview'
-                              ' to generate a preview for your poll')
+    update.message.reply_text(
+        'Please select /poll to get a Poll, /quiz to get a Quiz or /preview'
+        ' to generate a preview for your poll'
+    )
 
 
-def poll(update, context):
+def poll(update: Update, context: CallbackContext) -> None:
     """Sends a predefined poll"""
     questions = ["Good", "Really good", "Fantastic", "Great"]
-    message = context.bot.send_poll(update.effective_chat.id, "How are you?", questions,
-                                    is_anonymous=False, allows_multiple_answers=True)
+    message = context.bot.send_poll(
+        update.effective_chat.id,
+        "How are you?",
+        questions,
+        is_anonymous=False,
+        allows_multiple_answers=True,
+    )
     # Save some info about the poll the bot_data for later use in receive_poll_answer
-    payload = {message.poll.id: {"questions": questions, "message_id": message.message_id,
-                                 "chat_id": update.effective_chat.id, "answers": 0}}
+    payload = {
+        message.poll.id: {
+            "questions": questions,
+            "message_id": message.message_id,
+            "chat_id": update.effective_chat.id,
+            "answers": 0,
+        }
+    }
     context.bot_data.update(payload)
 
 
-def receive_poll_answer(update, context):
+def receive_poll_answer(update: Update, context: CallbackContext) -> None:
     """Summarize a users poll vote"""
     answer = update.poll_answer
     poll_id = answer.poll_id
@@ -52,29 +81,33 @@ def receive_poll_answer(update, context):
             answer_string += questions[question_id] + " and "
         else:
             answer_string += questions[question_id]
-    context.bot.send_message(context.bot_data[poll_id]["chat_id"],
-                             "{} feels {}!".format(update.effective_user.mention_html(),
-                                                   answer_string),
-                             parse_mode=ParseMode.HTML)
+    context.bot.send_message(
+        context.bot_data[poll_id]["chat_id"],
+        f"{update.effective_user.mention_html()} feels {answer_string}!",
+        parse_mode=ParseMode.HTML,
+    )
     context.bot_data[poll_id]["answers"] += 1
     # Close poll after three participants voted
     if context.bot_data[poll_id]["answers"] == 3:
-        context.bot.stop_poll(context.bot_data[poll_id]["chat_id"],
-                              context.bot_data[poll_id]["message_id"])
+        context.bot.stop_poll(
+            context.bot_data[poll_id]["chat_id"], context.bot_data[poll_id]["message_id"]
+        )
 
 
-def quiz(update, context):
+def quiz(update: Update, context: CallbackContext) -> None:
     """Send a predefined poll"""
     questions = ["1", "2", "4", "20"]
-    message = update.effective_message.reply_poll("How many eggs do you need for a cake?",
-                                                  questions, type=Poll.QUIZ, correct_option_id=2)
+    message = update.effective_message.reply_poll(
+        "How many eggs do you need for a cake?", questions, type=Poll.QUIZ, correct_option_id=2
+    )
     # Save some info about the poll the bot_data for later use in receive_quiz_answer
-    payload = {message.poll.id: {"chat_id": update.effective_chat.id,
-                                 "message_id": message.message_id}}
+    payload = {
+        message.poll.id: {"chat_id": update.effective_chat.id, "message_id": message.message_id}
+    }
     context.bot_data.update(payload)
 
 
-def receive_quiz_answer(update, context):
+def receive_quiz_answer(update: Update, context: CallbackContext) -> None:
     """Close quiz after three participants took it"""
     # the bot can receive closed poll updates we don't care about
     if update.poll.is_closed:
@@ -88,18 +121,18 @@ def receive_quiz_answer(update, context):
         context.bot.stop_poll(quiz_data["chat_id"], quiz_data["message_id"])
 
 
-def preview(update, context):
+def preview(update: Update, context: CallbackContext) -> None:
     """Ask user to create a poll and display a preview of it"""
     # using this without a type lets the user chooses what he wants (quiz or poll)
     button = [[KeyboardButton("Press me!", request_poll=KeyboardButtonPollType())]]
     message = "Press the button to let the bot generate a preview for your poll"
     # using one_time_keyboard to hide the keyboard
-    update.effective_message.reply_text(message,
-                                        reply_markup=ReplyKeyboardMarkup(button,
-                                                                         one_time_keyboard=True))
+    update.effective_message.reply_text(
+        message, reply_markup=ReplyKeyboardMarkup(button, one_time_keyboard=True)
+    )
 
 
-def receive_poll(update, context):
+def receive_poll(update: Update, context: CallbackContext) -> None:
     """On receiving polls, reply to it by a closed poll copying the received poll"""
     actual_poll = update.effective_message.poll
     # Only need to set the question and options, since all other parameters don't matter for
@@ -109,30 +142,27 @@ def receive_poll(update, context):
         options=[o.text for o in actual_poll.options],
         # with is_closed true, the poll/quiz is immediately closed
         is_closed=True,
-        reply_markup=ReplyKeyboardRemove()
+        reply_markup=ReplyKeyboardRemove(),
     )
 
 
-def help_handler(update, context):
+def help_handler(update: Update, context: CallbackContext) -> None:
     """Display a help message"""
-    update.message.reply_text("Use /quiz, /poll or /preview to test this "
-                              "bot.")
+    update.message.reply_text("Use /quiz, /poll or /preview to test this " "bot.")
 
 
-def main():
+def main() -> None:
     # Create the Updater and pass it your bot's token.
-    # Make sure to set use_context=True to use the new context based callbacks
-    # Post version 12 this will no longer be necessary
-    updater = Updater("TOKEN", use_context=True)
-    dp = updater.dispatcher
-    dp.add_handler(CommandHandler('start', start))
-    dp.add_handler(CommandHandler('poll', poll))
-    dp.add_handler(PollAnswerHandler(receive_poll_answer))
-    dp.add_handler(CommandHandler('quiz', quiz))
-    dp.add_handler(PollHandler(receive_quiz_answer))
-    dp.add_handler(CommandHandler('preview', preview))
-    dp.add_handler(MessageHandler(Filters.poll, receive_poll))
-    dp.add_handler(CommandHandler('help', help_handler))
+    updater = Updater("TOKEN")
+    dispatcher = updater.dispatcher
+    dispatcher.add_handler(CommandHandler('start', start))
+    dispatcher.add_handler(CommandHandler('poll', poll))
+    dispatcher.add_handler(PollAnswerHandler(receive_poll_answer))
+    dispatcher.add_handler(CommandHandler('quiz', quiz))
+    dispatcher.add_handler(PollHandler(receive_quiz_answer))
+    dispatcher.add_handler(CommandHandler('preview', preview))
+    dispatcher.add_handler(MessageHandler(Filters.poll, receive_poll))
+    dispatcher.add_handler(CommandHandler('help', help_handler))
 
     # Start the Bot
     updater.start_polling()

examples/rawapibot.py

@@ -1,32 +1,34 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
+# pylint: disable=W0603
 """Simple Bot to reply to Telegram messages.
 
-This is built on the API wrapper, see rawapibot.py to see the same example built
+This is built on the API wrapper, see echobot.py to see the same example built
 on the telegram.ext bot framework.
 This program is dedicated to the public domain under the CC0 license.
 """
 import logging
-import telegram
-from telegram.error import NetworkError, Unauthorized
+from typing import NoReturn
 from time import sleep
 
-
-update_id = None
+import telegram
+from telegram.error import NetworkError, Unauthorized
 
 
-def main():
+UPDATE_ID = None
+
+
+def main() -> NoReturn:
     """Run the bot."""
-    global update_id
+    global UPDATE_ID
     # Telegram Bot Authorization Token
     bot = telegram.Bot('TOKEN')
 
     # get the first pending update_id, this is so we can skip over it in case
     # we get an "Unauthorized" exception.
     try:
-        update_id = bot.get_updates()[0].update_id
+        UPDATE_ID = bot.get_updates()[0].update_id
     except IndexError:
-        update_id = None
+        UPDATE_ID = None
 
     logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
 
@@ -37,19 +39,20 @@ def main():
             sleep(1)
         except Unauthorized:
             # The user has removed or blocked the bot.
-            update_id += 1
+            UPDATE_ID += 1  # type: ignore[operator]
 
 
-def echo(bot):
+def echo(bot: telegram.Bot) -> None:
     """Echo the message the user sent."""
-    global update_id
+    global UPDATE_ID
     # Request updates after the last update_id
-    for update in bot.get_updates(offset=update_id, timeout=10):
-        update_id = update.update_id + 1
+    for update in bot.get_updates(offset=UPDATE_ID, timeout=10):
+        UPDATE_ID = update.update_id + 1
 
         if update.message:  # your bot can receive updates without messages
-            # Reply to the message
-            update.message.reply_text(update.message.text)
+            if update.message.text:  # not all messages contain text
+                # Reply to the message
+                update.message.reply_text(update.message.text)
 
 
 if __name__ == '__main__':

examples/timerbot.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python
-# -*- coding: utf-8 -*-
+# pylint: disable=W0613, C0116
+# type: ignore[union-attr]
 # This program is dedicated to the public domain under the CC0 license.
 
 """
@@ -20,18 +21,20 @@ bot.
 
 import logging
 
-from telegram.ext import Updater, CommandHandler
+from telegram import Update
+from telegram.ext import Updater, CommandHandler, CallbackContext
 
 # Enable logging
-logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-                    level=logging.INFO)
+logging.basicConfig(
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', level=logging.INFO
+)
 
 logger = logging.getLogger(__name__)
 
 
 # Define a few command handlers. These usually take the two arguments update and
 # context. Error handlers also receive the raised TelegramError object in error.
-def start(update, context):
+def start(update: Update, context: CallbackContext) -> None:
     update.message.reply_text('Hi! Use /set <seconds> to set a timer')
 
 
@@ -41,7 +44,17 @@ def alarm(context):
     context.bot.send_message(job.context, text='Beep!')
 
 
-def set_timer(update, context):
+def remove_job_if_exists(name, context):
+    """Remove job with given name. Returns whether job was removed."""
+    current_jobs = context.job_queue.get_jobs_by_name(name)
+    if not current_jobs:
+        return False
+    for job in current_jobs:
+        job.schedule_removal()
+    return True
+
+
+def set_timer(update: Update, context: CallbackContext) -> None:
     """Add a job to the queue."""
     chat_id = update.message.chat_id
     try:
@@ -51,50 +64,39 @@ def set_timer(update, context):
             update.message.reply_text('Sorry we can not go back to future!')
             return
 
-        # Add job to queue and stop current one if there is a timer already
-        if 'job' in context.chat_data:
-            old_job = context.chat_data['job']
-            old_job.schedule_removal()
-        new_job = context.job_queue.run_once(alarm, due, context=chat_id)
-        context.chat_data['job'] = new_job
+        job_removed = remove_job_if_exists(str(chat_id), context)
+        context.job_queue.run_once(alarm, due, context=chat_id, name=str(chat_id))
 
-        update.message.reply_text('Timer successfully set!')
+        text = 'Timer successfully set!'
+        if job_removed:
+            text += ' Old one was removed.'
+        update.message.reply_text(text)
 
     except (IndexError, ValueError):
         update.message.reply_text('Usage: /set <seconds>')
 
 
-def unset(update, context):
+def unset(update: Update, context: CallbackContext) -> None:
     """Remove the job if the user changed their mind."""
-    if 'job' not in context.chat_data:
-        update.message.reply_text('You have no active timer')
-        return
-
-    job = context.chat_data['job']
-    job.schedule_removal()
-    del context.chat_data['job']
-
-    update.message.reply_text('Timer successfully unset!')
+    chat_id = update.message.chat_id
+    job_removed = remove_job_if_exists(str(chat_id), context)
+    text = 'Timer successfully cancelled!' if job_removed else 'You have no active timer.'
+    update.message.reply_text(text)
 
 
 def main():
     """Run bot."""
     # Create the Updater and pass it your bot's token.
-    # Make sure to set use_context=True to use the new context based callbacks
-    # Post version 12 this will no longer be necessary
-    updater = Updater("TOKEN", use_context=True)
+    updater = Updater("TOKEN")
 
     # Get the dispatcher to register handlers
-    dp = updater.dispatcher
+    dispatcher = updater.dispatcher
 
     # on different commands - answer in Telegram
-    dp.add_handler(CommandHandler("start", start))
-    dp.add_handler(CommandHandler("help", start))
-    dp.add_handler(CommandHandler("set", set_timer,
-                                  pass_args=True,
-                                  pass_job_queue=True,
-                                  pass_chat_data=True))
-    dp.add_handler(CommandHandler("unset", unset, pass_chat_data=True))
+    dispatcher.add_handler(CommandHandler("start", start))
+    dispatcher.add_handler(CommandHandler("help", start))
+    dispatcher.add_handler(CommandHandler("set", set_timer))
+    dispatcher.add_handler(CommandHandler("unset", unset))
 
     # Start the Bot
     updater.start_polling()

pyproject.toml

@@ -0,0 +1,11 @@
+[tool.black]
+line-length = 99
+target-version = ['py36']
+skip-string-normalization = true
+
+# We need to force-exclude the negated include pattern
+# so that pre-commit run --all-files does the correct thing
+# see https://github.com/psf/black/issues/1778
+force-exclude = '^(?!/(telegram|examples|tests)/).*\.py$'
+include = '(telegram|examples|tests)/.*\.py$'
+exclude = 'telegram/vendor'

requirements-dev.txt

@@ -1,12 +1,16 @@
-flake8
-pep257
-pylint
-flaky
-yapf
-mypy==0.770
 pre-commit
-beautifulsoup4
+# Make sure that the versions specified here match the pre-commit settings
+black==20.8b1
+flake8==3.8.4
+pylint==2.6.0
+mypy==0.790
+pyupgrade==2.7.4
+
 pytest==4.2.0
+# Need older attrs version for pytest 4.2.0
+attrs==19.1.0
+
+flaky
+beautifulsoup4
 pytest-timeout
 wheel
-attrs==19.1.0

requirements.txt

@@ -1,5 +1,6 @@
 certifi
-tornado>=5.1
 cryptography
-decorator>=4.4.0
+# only telegram.ext: # Keep this line here; used in setup(-raw).py
+tornado>=5.1
 APScheduler==3.6.3
+pytz>=2018.6

setup-raw.py

@@ -0,0 +1,7 @@
+#!/usr/bin/env python
+"""The setup and build script for the python-telegram-bot-raw library."""
+
+from setuptools import setup
+from setup import get_setup_kwargs
+
+setup(**get_setup_kwargs(raw=True))

setup.cfg

@@ -1,6 +1,3 @@
-[wheel]
-universal = 1
-
 [metadata]
 license_file = LICENSE.dual
 
@@ -15,12 +12,14 @@ upload-dir = docs/build/html
 [flake8]
 max-line-length = 99
 ignore = W503, W605
-exclude = setup.py, docs/source/conf.py
+extend-ignore = E203
+exclude = setup.py, setup-raw.py docs/source/conf.py, telegram/vendor
 
-[yapf]
-based_on_style = google
-split_before_logical_operator = True
-column_limit = 99
+[pylint]
+ignore=vendor
+
+[pylint.message-control]
+disable = C0330,R0801,R0913,R0904,R0903,R0902,W0511,C0116,C0115,W0703,R0914,R0914,C0302,R0912,R0915,R0401
 
 [tool:pytest]
 testpaths = tests
@@ -59,3 +58,9 @@ ignore_errors = True
 # We don't want to clutter the code with 'if self.bot is None: raise RuntimeError()'
 [mypy-telegram.callbackquery,telegram.chat,telegram.message,telegram.user,telegram.files.*,telegram.inline.inlinequery,telegram.payment.precheckoutquery,telegram.payment.shippingquery,telegram.passport.passportdata,telegram.passport.credentials,telegram.passport.passportfile,telegram.ext.filters]
 strict_optional = False
+
+[mypy-urllib3.*]
+ignore_missing_imports = True
+
+[mypy-apscheduler.*]
+ignore_missing_imports = True

setup.py

@@ -3,65 +3,120 @@
 
 import codecs
 import os
+import subprocess
 import sys
 
 from setuptools import setup, find_packages
 
+UPSTREAM_URLLIB3_FLAG = '--with-upstream-urllib3'
 
-def requirements():
+
+def get_requirements(raw=False):
     """Build the requirements list for this project"""
     requirements_list = []
 
-    with open('requirements.txt') as requirements:
-        for install in requirements:
+    with open('requirements.txt') as reqs:
+        for install in reqs:
+            if install.startswith('# only telegram.ext:'):
+                if raw:
+                    break
+                continue
             requirements_list.append(install.strip())
 
     return requirements_list
 
 
-packages = find_packages(exclude=['tests*'])
-requirements = requirements()
+def get_packages_requirements(raw=False):
+    """Build the package & requirements list for this project"""
+    reqs = get_requirements(raw=raw)
 
-# Allow for a package install to not use the vendored urllib3
-UPSTREAM_URLLIB3_FLAG = '--with-upstream-urllib3'
-if UPSTREAM_URLLIB3_FLAG in sys.argv:
-    sys.argv.remove(UPSTREAM_URLLIB3_FLAG)
-    requirements.append('urllib3 >= 1.19.1')
-    packages = [x for x in packages if not x.startswith('telegram.vendor.ptb_urllib3')]
+    exclude = ['tests*']
+    if raw:
+        exclude.append('telegram.ext*')
+
+    packs = find_packages(exclude=exclude)
+    # Allow for a package install to not use the vendored urllib3
+    if UPSTREAM_URLLIB3_FLAG in sys.argv:
+        sys.argv.remove(UPSTREAM_URLLIB3_FLAG)
+        reqs.append('urllib3 >= 1.19.1')
+        packs = [x for x in packs if not x.startswith('telegram.vendor.ptb_urllib3')]
+
+    return packs, reqs
+
+
+def get_setup_kwargs(raw=False):
+    """Builds a dictionary of kwargs for the setup function"""
+    packages, requirements = get_packages_requirements(raw=raw)
+
+    raw_ext = "-raw" if raw else ""
+    readme = f'README{"_RAW" if raw else ""}.rst'
 
-with codecs.open('README.rst', 'r', 'utf-8') as fd:
     fn = os.path.join('telegram', 'version.py')
     with open(fn) as fh:
         code = compile(fh.read(), fn, 'exec')
         exec(code)
 
-    setup(name='python-telegram-bot',
-          version=__version__,
-          author='Leandro Toledo',
-          author_email='devs@python-telegram-bot.org',
-          license='LGPLv3',
-          url='https://python-telegram-bot.org/',
-          keywords='python telegram bot api wrapper',
-          description="We have made you a wrapper you can't refuse",
-          long_description=fd.read(),
-          packages=packages,
-          install_requires=requirements,
-          extras_require={
-              'json': 'ujson',
-              'socks': 'PySocks'
-          },
-          include_package_data=True,
-          classifiers=[
-              'Development Status :: 5 - Production/Stable',
-              'Intended Audience :: Developers',
-              'License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)',
-              'Operating System :: OS Independent',
-              'Topic :: Software Development :: Libraries :: Python Modules',
-              'Topic :: Communications :: Chat',
-              'Topic :: Internet',
-              'Programming Language :: Python',
-              'Programming Language :: Python :: 3',
-              'Programming Language :: Python :: 3.6',
-              'Programming Language :: Python :: 3.7',
-              'Programming Language :: Python :: 3.8',
-          ],)
+    with open(readme, 'r', encoding='utf-8') as fd:
+
+        kwargs = dict(
+            script_name=f'setup{raw_ext}.py',
+            name=f'python-telegram-bot{raw_ext}',
+            version=locals()['__version__'],
+            author='Leandro Toledo',
+            author_email='devs@python-telegram-bot.org',
+            license='LGPLv3',
+            url='https://python-telegram-bot.org/',
+            # Keywords supported by PyPI can be found at https://git.io/JtLIZ
+            project_urls={
+                "Documentation": "https://python-telegram-bot.readthedocs.io",
+                "Bug Tracker": "https://github.com/python-telegram-bot/python-telegram-bot/issues",
+                "Source Code": "https://github.com/python-telegram-bot/python-telegram-bot",
+                "News": "https://t.me/pythontelegrambotchannel",
+                "Changelog": "https://python-telegram-bot.readthedocs.io/en/stable/changelog.html",
+            },
+            download_url=f'https://pypi.org/project/python-telegram-bot{raw_ext}/',
+            keywords='python telegram bot api wrapper',
+            description="We have made you a wrapper you can't refuse",
+            long_description=fd.read(),
+            long_description_content_type='text/x-rst',
+            packages=packages,
+
+            install_requires=requirements,
+            extras_require={
+                'json': 'ujson',
+                'socks': 'PySocks'
+            },
+            include_package_data=True,
+            classifiers=[
+                'Development Status :: 5 - Production/Stable',
+                'Intended Audience :: Developers',
+                'License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)',
+                'Operating System :: OS Independent',
+                'Topic :: Software Development :: Libraries :: Python Modules',
+                'Topic :: Communications :: Chat',
+                'Topic :: Internet',
+                'Programming Language :: Python',
+                'Programming Language :: Python :: 3',
+                'Programming Language :: Python :: 3.6',
+                'Programming Language :: Python :: 3.7',
+                'Programming Language :: Python :: 3.8',
+                'Programming Language :: Python :: 3.9',
+            ],
+            python_requires='>=3.6'
+        )
+
+    return kwargs
+
+
+def main():
+    # If we're building, build ptb-raw as well
+    if set(sys.argv[1:]) in [{'bdist_wheel'}, {'sdist'}, {'sdist', 'bdist_wheel'}]:
+        args = ['python', 'setup-raw.py']
+        args.extend(sys.argv[1:])
+        subprocess.run(args, check=True, capture_output=True)
+
+    setup(**get_setup_kwargs(raw=False))
+
+
+if __name__ == '__main__':
+    main()

telegram/__init__.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -23,6 +23,7 @@ from .botcommand import BotCommand
 from .user import User
 from .files.chatphoto import ChatPhoto
 from .chat import Chat
+from .chatlocation import ChatLocation
 from .chatmember import ChatMember
 from .chatpermissions import ChatPermissions
 from .files.photosize import PhotoSize
@@ -50,9 +51,11 @@ from .files.inputfile import InputFile
 from .files.file import File
 from .parsemode import ParseMode
 from .messageentity import MessageEntity
+from .messageid import MessageId
 from .games.game import Game
 from .poll import Poll, PollOption, PollAnswer
 from .loginurl import LoginUrl
+from .proximityalerttriggered import ProximityAlertTriggered
 from .games.callbackgame import CallbackGame
 from .payment.shippingaddress import ShippingAddress
 from .payment.orderinfo import OrderInfo
@@ -102,63 +105,173 @@ from .payment.shippingquery import ShippingQuery
 from .webhookinfo import WebhookInfo
 from .games.gamehighscore import GameHighScore
 from .update import Update
-from .files.inputmedia import (InputMedia, InputMediaVideo, InputMediaPhoto, InputMediaAnimation,
-                               InputMediaAudio, InputMediaDocument)
-from .constants import (MAX_MESSAGE_LENGTH, MAX_CAPTION_LENGTH, SUPPORTED_WEBHOOK_PORTS,
-                        MAX_FILESIZE_DOWNLOAD, MAX_FILESIZE_UPLOAD,
-                        MAX_MESSAGES_PER_SECOND_PER_CHAT, MAX_MESSAGES_PER_SECOND,
-                        MAX_MESSAGES_PER_MINUTE_PER_GROUP)
-from .passport.passportelementerrors import (PassportElementError,
-                                             PassportElementErrorDataField,
-                                             PassportElementErrorFile,
-                                             PassportElementErrorFiles,
-                                             PassportElementErrorFrontSide,
-                                             PassportElementErrorReverseSide,
-                                             PassportElementErrorSelfie,
-                                             PassportElementErrorTranslationFile,
-                                             PassportElementErrorTranslationFiles,
-                                             PassportElementErrorUnspecified)
-from .passport.credentials import (Credentials,
-                                   DataCredentials,
-                                   SecureData,
-                                   FileCredentials,
-                                   TelegramDecryptionError)
+from .files.inputmedia import (
+    InputMedia,
+    InputMediaVideo,
+    InputMediaPhoto,
+    InputMediaAnimation,
+    InputMediaAudio,
+    InputMediaDocument,
+)
+from .constants import (
+    MAX_MESSAGE_LENGTH,
+    MAX_CAPTION_LENGTH,
+    SUPPORTED_WEBHOOK_PORTS,
+    MAX_FILESIZE_DOWNLOAD,
+    MAX_FILESIZE_UPLOAD,
+    MAX_MESSAGES_PER_SECOND_PER_CHAT,
+    MAX_MESSAGES_PER_SECOND,
+    MAX_MESSAGES_PER_MINUTE_PER_GROUP,
+)
+from .passport.passportelementerrors import (
+    PassportElementError,
+    PassportElementErrorDataField,
+    PassportElementErrorFile,
+    PassportElementErrorFiles,
+    PassportElementErrorFrontSide,
+    PassportElementErrorReverseSide,
+    PassportElementErrorSelfie,
+    PassportElementErrorTranslationFile,
+    PassportElementErrorTranslationFiles,
+    PassportElementErrorUnspecified,
+)
+from .passport.credentials import (
+    Credentials,
+    DataCredentials,
+    SecureData,
+    FileCredentials,
+    TelegramDecryptionError,
+)
 from .bot import Bot
 from .version import __version__  # noqa: F401
 
 __author__ = 'devs@python-telegram-bot.org'
 
 __all__ = [
-    'Audio', 'Bot', 'Chat', 'ChatMember', 'ChatPermissions', 'ChatAction', 'ChosenInlineResult',
-    'CallbackQuery', 'Contact', 'Document', 'File', 'ForceReply', 'InlineKeyboardButton',
-    'InlineKeyboardMarkup', 'InlineQuery', 'InlineQueryResult', 'InlineQueryResult',
-    'InlineQueryResultArticle', 'InlineQueryResultAudio', 'InlineQueryResultCachedAudio',
-    'InlineQueryResultCachedDocument', 'InlineQueryResultCachedGif',
-    'InlineQueryResultCachedMpeg4Gif', 'InlineQueryResultCachedPhoto',
-    'InlineQueryResultCachedSticker', 'InlineQueryResultCachedVideo',
-    'InlineQueryResultCachedVoice', 'InlineQueryResultContact', 'InlineQueryResultDocument',
-    'InlineQueryResultGif', 'InlineQueryResultLocation', 'InlineQueryResultMpeg4Gif',
-    'InlineQueryResultPhoto', 'InlineQueryResultVenue', 'InlineQueryResultVideo',
-    'InlineQueryResultVoice', 'InlineQueryResultGame', 'InputContactMessageContent', 'InputFile',
-    'InputLocationMessageContent', 'InputMessageContent', 'InputTextMessageContent',
-    'InputVenueMessageContent', 'Location', 'EncryptedCredentials',
-    'PassportFile', 'EncryptedPassportElement', 'PassportData', 'Message', 'MessageEntity',
-    'ParseMode', 'PhotoSize', 'ReplyKeyboardRemove', 'ReplyKeyboardMarkup', 'ReplyMarkup',
-    'Sticker', 'TelegramError', 'TelegramObject', 'Update', 'User', 'UserProfilePhotos', 'Venue',
-    'Video', 'Voice', 'MAX_MESSAGE_LENGTH', 'MAX_CAPTION_LENGTH', 'SUPPORTED_WEBHOOK_PORTS',
-    'MAX_FILESIZE_DOWNLOAD', 'MAX_FILESIZE_UPLOAD', 'MAX_MESSAGES_PER_SECOND_PER_CHAT',
-    'MAX_MESSAGES_PER_SECOND', 'MAX_MESSAGES_PER_MINUTE_PER_GROUP', 'WebhookInfo', 'Animation',
-    'Game', 'GameHighScore', 'VideoNote', 'LabeledPrice', 'SuccessfulPayment', 'ShippingOption',
-    'ShippingAddress', 'PreCheckoutQuery', 'OrderInfo', 'Invoice', 'ShippingQuery', 'ChatPhoto',
-    'StickerSet', 'MaskPosition', 'CallbackGame', 'InputMedia', 'InputMediaPhoto',
-    'InputMediaVideo', 'PassportElementError', 'PassportElementErrorFile',
-    'PassportElementErrorReverseSide', 'PassportElementErrorFrontSide',
-    'PassportElementErrorFiles', 'PassportElementErrorDataField', 'PassportElementErrorFile',
-    'Credentials', 'DataCredentials', 'SecureData', 'FileCredentials', 'IdDocumentData',
-    'PersonalDetails', 'ResidentialAddress', 'InputMediaVideo', 'InputMediaAnimation',
-    'InputMediaAudio', 'InputMediaDocument', 'TelegramDecryptionError',
-    'PassportElementErrorSelfie', 'PassportElementErrorTranslationFile',
-    'PassportElementErrorTranslationFiles', 'PassportElementErrorUnspecified', 'Poll',
-    'PollOption', 'PollAnswer', 'LoginUrl', 'KeyboardButton', 'KeyboardButtonPollType', 'Dice',
-    'BotCommand'
+    'Audio',
+    'Bot',
+    'Chat',
+    'ChatMember',
+    'ChatPermissions',
+    'ChatAction',
+    'ChosenInlineResult',
+    'CallbackQuery',
+    'Contact',
+    'Document',
+    'File',
+    'ForceReply',
+    'InlineKeyboardButton',
+    'InlineKeyboardMarkup',
+    'InlineQuery',
+    'InlineQueryResult',
+    'InlineQueryResult',
+    'InlineQueryResultArticle',
+    'InlineQueryResultAudio',
+    'InlineQueryResultCachedAudio',
+    'InlineQueryResultCachedDocument',
+    'InlineQueryResultCachedGif',
+    'InlineQueryResultCachedMpeg4Gif',
+    'InlineQueryResultCachedPhoto',
+    'InlineQueryResultCachedSticker',
+    'InlineQueryResultCachedVideo',
+    'InlineQueryResultCachedVoice',
+    'InlineQueryResultContact',
+    'InlineQueryResultDocument',
+    'InlineQueryResultGif',
+    'InlineQueryResultLocation',
+    'InlineQueryResultMpeg4Gif',
+    'InlineQueryResultPhoto',
+    'InlineQueryResultVenue',
+    'InlineQueryResultVideo',
+    'InlineQueryResultVoice',
+    'InlineQueryResultGame',
+    'InputContactMessageContent',
+    'InputFile',
+    'InputLocationMessageContent',
+    'InputMessageContent',
+    'InputTextMessageContent',
+    'InputVenueMessageContent',
+    'Location',
+    'ChatLocation',
+    'ProximityAlertTriggered',
+    'EncryptedCredentials',
+    'PassportFile',
+    'EncryptedPassportElement',
+    'PassportData',
+    'Message',
+    'MessageEntity',
+    'ParseMode',
+    'PhotoSize',
+    'ReplyKeyboardRemove',
+    'ReplyKeyboardMarkup',
+    'ReplyMarkup',
+    'Sticker',
+    'TelegramError',
+    'TelegramObject',
+    'Update',
+    'User',
+    'UserProfilePhotos',
+    'Venue',
+    'Video',
+    'Voice',
+    'MAX_MESSAGE_LENGTH',
+    'MAX_CAPTION_LENGTH',
+    'SUPPORTED_WEBHOOK_PORTS',
+    'MAX_FILESIZE_DOWNLOAD',
+    'MAX_FILESIZE_UPLOAD',
+    'MAX_MESSAGES_PER_SECOND_PER_CHAT',
+    'MAX_MESSAGES_PER_SECOND',
+    'MAX_MESSAGES_PER_MINUTE_PER_GROUP',
+    'WebhookInfo',
+    'Animation',
+    'Game',
+    'GameHighScore',
+    'VideoNote',
+    'LabeledPrice',
+    'SuccessfulPayment',
+    'ShippingOption',
+    'ShippingAddress',
+    'PreCheckoutQuery',
+    'OrderInfo',
+    'Invoice',
+    'ShippingQuery',
+    'ChatPhoto',
+    'StickerSet',
+    'MaskPosition',
+    'CallbackGame',
+    'InputMedia',
+    'InputMediaPhoto',
+    'InputMediaVideo',
+    'PassportElementError',
+    'PassportElementErrorFile',
+    'PassportElementErrorReverseSide',
+    'PassportElementErrorFrontSide',
+    'PassportElementErrorFiles',
+    'PassportElementErrorDataField',
+    'PassportElementErrorFile',
+    'Credentials',
+    'DataCredentials',
+    'SecureData',
+    'FileCredentials',
+    'IdDocumentData',
+    'PersonalDetails',
+    'ResidentialAddress',
+    'InputMediaVideo',
+    'InputMediaAnimation',
+    'InputMediaAudio',
+    'InputMediaDocument',
+    'TelegramDecryptionError',
+    'PassportElementErrorSelfie',
+    'PassportElementErrorTranslationFile',
+    'PassportElementErrorTranslationFiles',
+    'PassportElementErrorUnspecified',
+    'Poll',
+    'PollOption',
+    'PollAnswer',
+    'LoginUrl',
+    'KeyboardButton',
+    'KeyboardButtonPollType',
+    'Dice',
+    'BotCommand',
+    'MessageId',
 ]

telegram/__main__.py

@@ -1,7 +1,7 @@
 # !/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -16,20 +16,21 @@
 #
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
-import sys
+# pylint: disable=E0401, C0114
 import subprocess
+import sys
+from typing import Optional
 
 import certifi
 
-from typing import Optional
-
 from . import __version__ as telegram_ver
 
 
 def _git_revision() -> Optional[str]:
     try:
-        output = subprocess.check_output(["git", "describe", "--long", "--tags"],
-                                         stderr=subprocess.STDOUT)
+        output = subprocess.check_output(
+            ["git", "describe", "--long", "--tags"], stderr=subprocess.STDOUT
+        )
     except (subprocess.SubprocessError, OSError):
         return None
     return output.decode().strip()
@@ -37,10 +38,10 @@ def _git_revision() -> Optional[str]:
 
 def print_ver_info() -> None:
     git_revision = _git_revision()
-    print('python-telegram-bot {}'.format(telegram_ver) + (' ({})'.format(git_revision)
-                                                           if git_revision else ''))
-    print('certifi {}'.format(certifi.__version__))  # type: ignore[attr-defined]
-    print('Python {}'.format(sys.version.replace('\n', ' ')))
+    print(f'python-telegram-bot {telegram_ver}' + (f' ({git_revision})' if git_revision else ''))
+    print(f'certifi {certifi.__version__}')  # type: ignore[attr-defined]
+    sys_version = sys.version.replace('\n', ' ')
+    print(f'Python {sys_version}')
 
 
 def main() -> None:

telegram/base.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -23,9 +23,9 @@ except ImportError:
     import json  # type: ignore[no-redef]
 
 import warnings
+from typing import TYPE_CHECKING, List, Optional, Tuple, Type, TypeVar
 
 from telegram.utils.types import JSONDict
-from typing import Tuple, Any, Optional, Type, TypeVar, TYPE_CHECKING, List
 
 if TYPE_CHECKING:
     from telegram import Bot
@@ -36,15 +36,12 @@ TO = TypeVar('TO', bound='TelegramObject', covariant=True)
 class TelegramObject:
     """Base class for most telegram objects."""
 
-    # def __init__(self, *args: Any, **kwargs: Any):
-    #     pass
-
-    _id_attrs: Tuple[Any, ...] = ()
+    _id_attrs: Tuple[object, ...] = ()
 
     def __str__(self) -> str:
         return str(self.to_dict())
 
-    def __getitem__(self, item: str) -> Any:
+    def __getitem__(self, item: str) -> object:
         return self.__dict__[item]
 
     @staticmethod
@@ -62,13 +59,10 @@ class TelegramObject:
 
         if cls == TelegramObject:
             return cls()
-        else:
-            return cls(bot=bot, **data)  # type: ignore[call-arg]
+        return cls(bot=bot, **data)  # type: ignore[call-arg]
 
     @classmethod
-    def de_list(cls: Type[TO],
-                data: Optional[List[JSONDict]],
-                bot: 'Bot') -> List[Optional[TO]]:
+    def de_list(cls: Type[TO], data: Optional[List[JSONDict]], bot: 'Bot') -> List[Optional[TO]]:
         if not data:
             return []
 
@@ -104,11 +98,15 @@ class TelegramObject:
     def __eq__(self, other: object) -> bool:
         if isinstance(other, self.__class__):
             if self._id_attrs == ():
-                warnings.warn("Objects of type {} can not be meaningfully tested for "
-                              "equivalence.".format(self.__class__.__name__))
+                warnings.warn(
+                    f"Objects of type {self.__class__.__name__} can not be meaningfully tested for"
+                    " equivalence."
+                )
             if other._id_attrs == ():
-                warnings.warn("Objects of type {} can not be meaningfully tested for "
-                              "equivalence.".format(other.__class__.__name__))
+                warnings.warn(
+                    f"Objects of type {other.__class__.__name__} can not be meaningfully tested"
+                    " for equivalence."
+                )
             return self._id_attrs == other._id_attrs
         return super().__eq__(other)  # pylint: disable=no-member
 

telegram/botcommand.py

@@ -2,7 +2,7 @@
 # pylint: disable=R0903
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,9 +18,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 Bot Command."""
-from telegram import TelegramObject
 from typing import Any
 
+from telegram import TelegramObject
+
 
 class BotCommand(TelegramObject):
     """
@@ -29,16 +30,18 @@ class BotCommand(TelegramObject):
     Objects of this class are comparable in terms of equality. Two objects of this class are
     considered equal, if their :attr:`command` and :attr:`description` are equal.
 
-    Attributes:
-        command (:obj:`str`): Text of the command.
-        description (:obj:`str`): Description of the command.
-
     Args:
         command (:obj:`str`): Text of the command, 1-32 characters. Can contain only lowercase
             English letters, digits and underscores.
         description (:obj:`str`): Description of the command, 3-256 characters.
+
+    Attributes:
+        command (:obj:`str`): Text of the command.
+        description (:obj:`str`): Description of the command.
+
     """
-    def __init__(self, command: str, description: str, **kwargs: Any):
+
+    def __init__(self, command: str, description: str, **_kwargs: Any):
         self.command = command
         self.description = description
 

telegram/callbackquery.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -16,14 +16,22 @@
 #
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
+# pylint: disable=W0622
 """This module contains an object that represents a Telegram CallbackQuery"""
-from telegram import TelegramObject, Message, User
+from typing import TYPE_CHECKING, Any, List, Optional, Union, Tuple, ClassVar
 
+from telegram import Message, TelegramObject, User, Location, ReplyMarkup, constants
 from telegram.utils.types import JSONDict
-from typing import Optional, Any, Union, TYPE_CHECKING, List
 
 if TYPE_CHECKING:
-    from telegram import Bot, InlineKeyboardMarkup, GameHighScore
+    from telegram import (
+        Bot,
+        GameHighScore,
+        InlineKeyboardMarkup,
+        MessageId,
+        InputMedia,
+        MessageEntity,
+    )
 
 
 class CallbackQuery(TelegramObject):
@@ -40,19 +48,10 @@ class CallbackQuery(TelegramObject):
     Note:
         * In Python `from` is a reserved word, use `from_user` instead.
         * Exactly one of the fields :attr:`data` or :attr:`game_short_name` will be present.
-
-    Attributes:
-        id (:obj:`str`): Unique identifier for this query.
-        from_user (:class:`telegram.User`): Sender.
-        chat_instance (:obj:`str`): Global identifier, uniquely corresponding to the chat to which
-            the message with the callback button was sent.
-        message (:class:`telegram.Message`): Optional. Message with the callback button that
-            originated the query.
-        data (:obj:`str`): Optional. Data associated with the callback button.
-        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.
+        * After the user presses an inline button, Telegram clients will display a progress bar
+          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).
 
     Args:
         id (:obj:`str`): Unique identifier for this query.
@@ -70,26 +69,35 @@ class CallbackQuery(TelegramObject):
             the unique identifier for the game
         bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
 
-    Note:
-        After the user presses an inline button, Telegram clients will display a progress bar
-        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).
+    Attributes:
+        id (:obj:`str`): Unique identifier for this query.
+        from_user (:class:`telegram.User`): Sender.
+        chat_instance (:obj:`str`): Global identifier, uniquely corresponding to the chat to which
+            the message with the callback button was sent.
+        message (:class:`telegram.Message`): Optional. Message with the callback button that
+            originated the query.
+        data (:obj:`str`): Optional. Data associated with the callback button.
+        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.
 
     """
 
-    def __init__(self,
-                 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):
+    def __init__(
+        self,
+        id: str,  # pylint: disable=W0622
+        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,
+    ):
         # Required
-        self.id = id
+        self.id = id  # pylint: disable=C0103
         self.from_user = from_user
         self.chat_instance = chat_instance
         # Optionals
@@ -114,49 +122,98 @@ class CallbackQuery(TelegramObject):
 
         return cls(bot=bot, **data)
 
-    def answer(self, *args: Any, **kwargs: Any) -> bool:
+    def answer(
+        self,
+        text: str = None,
+        show_alert: bool = False,
+        url: str = None,
+        cache_time: int = None,
+        timeout: float = None,
+        api_kwargs: JSONDict = None,
+    ) -> bool:
         """Shortcut for::
 
             bot.answer_callback_query(update.callback_query.id, *args, **kwargs)
 
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.answer_callback_query`.
+
         Returns:
             :obj:`bool`: On success, :obj:`True` is returned.
 
         """
-        return self.bot.answer_callback_query(self.id, *args, **kwargs)
+        return self.bot.answer_callback_query(
+            callback_query_id=self.id,
+            text=text,
+            show_alert=show_alert,
+            url=url,
+            cache_time=cache_time,
+            timeout=timeout,
+            api_kwargs=api_kwargs,
+        )
 
-    def edit_message_text(self, text: str, *args: Any, **kwargs: Any) -> Union[Message, bool]:
+    def edit_message_text(
+        self,
+        text: str,
+        parse_mode: str = None,
+        disable_web_page_preview: bool = None,
+        reply_markup: 'InlineKeyboardMarkup' = None,
+        timeout: float = None,
+        api_kwargs: JSONDict = None,
+        entities: Union[List['MessageEntity'], Tuple['MessageEntity', ...]] = None,
+    ) -> Union[Message, bool]:
         """Shortcut for either::
 
-            bot.edit_message_text(text, chat_id=update.callback_query.message.chat_id,
-                                message_id=update.callback_query.message.message_id,
-                                *args, **kwargs)
+            update.callback_query.message.edit_text(text, *args, **kwargs)
 
         or::
 
             bot.edit_message_text(text, inline_message_id=update.callback_query.inline_message_id,
                                 *args, **kwargs)
 
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.edit_message_text`.
+
         Returns:
             :class:`telegram.Message`: On success, if edited message is sent by the bot, the
             edited Message is returned, otherwise :obj:`True` is returned.
 
         """
         if self.inline_message_id:
-            return self.bot.edit_message_text(text, inline_message_id=self.inline_message_id,
-                                              *args, **kwargs)
-        else:
-            return self.bot.edit_message_text(text, chat_id=self.message.chat_id,
-                                              message_id=self.message.message_id, *args, **kwargs)
+            return self.bot.edit_message_text(
+                inline_message_id=self.inline_message_id,
+                text=text,
+                parse_mode=parse_mode,
+                disable_web_page_preview=disable_web_page_preview,
+                reply_markup=reply_markup,
+                timeout=timeout,
+                api_kwargs=api_kwargs,
+                entities=entities,
+                chat_id=None,
+                message_id=None,
+            )
+        return self.message.edit_text(
+            text=text,
+            parse_mode=parse_mode,
+            disable_web_page_preview=disable_web_page_preview,
+            reply_markup=reply_markup,
+            timeout=timeout,
+            api_kwargs=api_kwargs,
+            entities=entities,
+        )
 
-    def edit_message_caption(self, caption: str, *args: Any,
-                             **kwargs: Any) -> Union[Message, bool]:
+    def edit_message_caption(
+        self,
+        caption: str = None,
+        reply_markup: 'InlineKeyboardMarkup' = None,
+        timeout: float = None,
+        parse_mode: str = None,
+        api_kwargs: JSONDict = None,
+        caption_entities: Union[List['MessageEntity'], Tuple['MessageEntity', ...]] = None,
+    ) -> Union[Message, bool]:
         """Shortcut for either::
 
-            bot.edit_message_caption(caption=caption,
-                                   chat_id=update.callback_query.message.chat_id,
-                                   message_id=update.callback_query.message.message_id,
-                                   *args, **kwargs)
+            update.callback_query.message.edit_caption(caption, *args, **kwargs)
 
         or::
 
@@ -164,34 +221,60 @@ class CallbackQuery(TelegramObject):
                                     inline_message_id=update.callback_query.inline_message_id,
                                    *args, **kwargs)
 
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.edit_message_caption`.
+
         Returns:
             :class:`telegram.Message`: On success, if edited message is sent by the bot, the
             edited Message is returned, otherwise :obj:`True` is returned.
 
         """
         if self.inline_message_id:
-            return self.bot.edit_message_caption(caption=caption,
-                                                 inline_message_id=self.inline_message_id,
-                                                 *args, **kwargs)
-        else:
-            return self.bot.edit_message_caption(caption=caption, chat_id=self.message.chat_id,
-                                                 message_id=self.message.message_id,
-                                                 *args, **kwargs)
+            return self.bot.edit_message_caption(
+                caption=caption,
+                inline_message_id=self.inline_message_id,
+                reply_markup=reply_markup,
+                timeout=timeout,
+                parse_mode=parse_mode,
+                api_kwargs=api_kwargs,
+                caption_entities=caption_entities,
+                chat_id=None,
+                message_id=None,
+            )
+        return self.message.edit_caption(
+            caption=caption,
+            reply_markup=reply_markup,
+            timeout=timeout,
+            parse_mode=parse_mode,
+            api_kwargs=api_kwargs,
+            caption_entities=caption_entities,
+        )
 
-    def edit_message_reply_markup(self, reply_markup: 'InlineKeyboardMarkup', *args: Any,
-                                  **kwargs: Any) -> Union[Message, bool]:
+    def edit_message_reply_markup(
+        self,
+        reply_markup: Optional['InlineKeyboardMarkup'] = None,
+        timeout: float = None,
+        api_kwargs: JSONDict = None,
+    ) -> Union[Message, bool]:
         """Shortcut for either::
 
-            bot.edit_message_reply_markup(chat_id=update.callback_query.message.chat_id,
-                                          message_id=update.callback_query.message.message_id,
-                                          reply_markup=reply_markup,
-                                          *args, **kwargs)
+            update.callback_query.message.edit_reply_markup(
+                reply_markup=reply_markup,
+                *args,
+                **kwargs
+            )
 
         or::
 
-            bot.edit_message_reply_markup(inline_message_id=update.callback_query.inline_message_id,
-                                        reply_markup=reply_markup,
-                                       *args, **kwargs)
+            bot.edit_message_reply_markup
+                inline_message_id=update.callback_query.inline_message_id,
+                reply_markup=reply_markup,
+                *args,
+                **kwargs
+            )
+
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.edit_message_reply_markup`.
 
         Returns:
             :class:`telegram.Message`: On success, if edited message is sent by the bot, the
@@ -199,149 +282,359 @@ class CallbackQuery(TelegramObject):
 
         """
         if self.inline_message_id:
-            return self.bot.edit_message_reply_markup(reply_markup=reply_markup,
-                                                      inline_message_id=self.inline_message_id,
-                                                      *args, **kwargs)
-        else:
-            return self.bot.edit_message_reply_markup(reply_markup=reply_markup,
-                                                      chat_id=self.message.chat_id,
-                                                      message_id=self.message.message_id,
-                                                      *args, **kwargs)
+            return self.bot.edit_message_reply_markup(
+                reply_markup=reply_markup,
+                inline_message_id=self.inline_message_id,
+                timeout=timeout,
+                api_kwargs=api_kwargs,
+                chat_id=None,
+                message_id=None,
+            )
+        return self.message.edit_reply_markup(
+            reply_markup=reply_markup,
+            timeout=timeout,
+            api_kwargs=api_kwargs,
+        )
 
-    def edit_message_media(self, *args: Any, **kwargs: Any) -> Union[Message, bool]:
+    def edit_message_media(
+        self,
+        media: 'InputMedia' = None,
+        reply_markup: 'InlineKeyboardMarkup' = None,
+        timeout: float = None,
+        api_kwargs: JSONDict = None,
+    ) -> Union[Message, bool]:
         """Shortcut for either::
 
-            bot.edit_message_media(chat_id=update.callback_query.message.chat_id,
-                                   message_id=update.callback_query.message.message_id,
-                                   media=media,
-                                   *args, **kwargs)
+            update.callback_query.message.edit_media(*args, **kwargs)
 
         or::
 
             bot.edit_message_media(inline_message_id=update.callback_query.inline_message_id,
-                                   media=media,
                                    *args, **kwargs)
 
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.edit_message_media`.
+
         Returns:
             :class:`telegram.Message`: On success, if edited message is sent by the bot, the
             edited Message is returned, otherwise :obj:`True` is returned.
 
         """
         if self.inline_message_id:
-            return self.bot.edit_message_media(inline_message_id=self.inline_message_id,
-                                               *args, **kwargs)
-        else:
-            return self.bot.edit_message_media(chat_id=self.message.chat_id,
-                                               message_id=self.message.message_id,
-                                               *args, **kwargs)
+            return self.bot.edit_message_media(
+                inline_message_id=self.inline_message_id,
+                media=media,
+                reply_markup=reply_markup,
+                timeout=timeout,
+                api_kwargs=api_kwargs,
+                chat_id=None,
+                message_id=None,
+            )
+        return self.message.edit_media(
+            media=media,
+            reply_markup=reply_markup,
+            timeout=timeout,
+            api_kwargs=api_kwargs,
+        )
 
-    def edit_message_live_location(self, *args: Any, **kwargs: Any) -> Union[Message, bool]:
+    def edit_message_live_location(
+        self,
+        latitude: float = None,
+        longitude: float = None,
+        location: Location = None,
+        reply_markup: 'InlineKeyboardMarkup' = None,
+        timeout: float = None,
+        api_kwargs: JSONDict = None,
+        horizontal_accuracy: float = None,
+        heading: int = None,
+        proximity_alert_radius: int = None,
+    ) -> Union[Message, bool]:
         """Shortcut for either::
 
-            bot.edit_message_live_location(chat_id=update.callback_query.message.chat_id,
-                                           message_id=update.callback_query.message.message_id,
-                                           reply_markup=reply_markup,
-                                           *args, **kwargs)
+            update.callback_query.message.edit_live_location(*args, **kwargs)
 
         or::
 
             bot.edit_message_live_location(
                 inline_message_id=update.callback_query.inline_message_id,
-                reply_markup=reply_markup,
                 *args, **kwargs
             )
 
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.edit_message_live_location`.
+
         Returns:
             :class:`telegram.Message`: On success, if edited message is sent by the bot, the
             edited Message is returned, otherwise :obj:`True` is returned.
 
         """
         if self.inline_message_id:
-            return self.bot.edit_message_live_location(inline_message_id=self.inline_message_id,
-                                                       *args, **kwargs)
-        else:
-            return self.bot.edit_message_live_location(chat_id=self.message.chat_id,
-                                                       message_id=self.message.message_id,
-                                                       *args, **kwargs)
+            return self.bot.edit_message_live_location(
+                inline_message_id=self.inline_message_id,
+                latitude=latitude,
+                longitude=longitude,
+                location=location,
+                reply_markup=reply_markup,
+                timeout=timeout,
+                api_kwargs=api_kwargs,
+                horizontal_accuracy=horizontal_accuracy,
+                heading=heading,
+                proximity_alert_radius=proximity_alert_radius,
+                chat_id=None,
+                message_id=None,
+            )
+        return self.message.edit_live_location(
+            latitude=latitude,
+            longitude=longitude,
+            location=location,
+            reply_markup=reply_markup,
+            timeout=timeout,
+            api_kwargs=api_kwargs,
+            horizontal_accuracy=horizontal_accuracy,
+            heading=heading,
+            proximity_alert_radius=proximity_alert_radius,
+        )
 
-    def stop_message_live_location(self, *args: Any, **kwargs: Any) -> Union[Message, bool]:
+    def stop_message_live_location(
+        self,
+        reply_markup: 'InlineKeyboardMarkup' = None,
+        timeout: float = None,
+        api_kwargs: JSONDict = None,
+    ) -> Union[Message, bool]:
         """Shortcut for either::
 
-            bot.stop_message_live_location(chat_id=update.callback_query.message.chat_id,
-                                           message_id=update.callback_query.message.message_id,
-                                           reply_markup=reply_markup,
-                                           *args, **kwargs)
+            update.callback_query.message.stop_live_location(*args, **kwargs)
 
         or::
 
             bot.stop_message_live_location(
                 inline_message_id=update.callback_query.inline_message_id,
-                reply_markup=reply_markup,
                 *args, **kwargs
             )
 
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.stop_message_live_location`.
+
         Returns:
             :class:`telegram.Message`: On success, if edited message is sent by the bot, the
             edited Message is returned, otherwise :obj:`True` is returned.
 
         """
         if self.inline_message_id:
-            return self.bot.stop_message_live_location(inline_message_id=self.inline_message_id,
-                                                       *args, **kwargs)
-        else:
-            return self.bot.stop_message_live_location(chat_id=self.message.chat_id,
-                                                       message_id=self.message.message_id,
-                                                       *args, **kwargs)
+            return self.bot.stop_message_live_location(
+                inline_message_id=self.inline_message_id,
+                reply_markup=reply_markup,
+                timeout=timeout,
+                api_kwargs=api_kwargs,
+                chat_id=None,
+                message_id=None,
+            )
+        return self.message.stop_live_location(
+            reply_markup=reply_markup,
+            timeout=timeout,
+            api_kwargs=api_kwargs,
+        )
 
-    def set_game_score(self, *args: Any, **kwargs: Any) -> Union[Message, bool]:
+    def set_game_score(
+        self,
+        user_id: Union[int, str],
+        score: int,
+        force: bool = None,
+        disable_edit_message: bool = None,
+        timeout: float = None,
+        api_kwargs: JSONDict = None,
+    ) -> Union[Message, bool]:
         """Shortcut for either::
 
-            bot.set_game_score(chat_id=update.callback_query.message.chat_id,
-                               message_id=update.callback_query.message.message_id,
-                               reply_markup=reply_markup,
-                               *args, **kwargs)
+           update.callback_query.message.set_game_score(*args, **kwargs)
 
         or::
 
             bot.set_game_score(inline_message_id=update.callback_query.inline_message_id,
-                               reply_markup=reply_markup,
                                *args, **kwargs)
 
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.set_game_score`.
+
         Returns:
             :class:`telegram.Message`: On success, if edited message is sent by the bot, the
             edited Message is returned, otherwise :obj:`True` is returned.
 
         """
         if self.inline_message_id:
-            return self.bot.set_game_score(inline_message_id=self.inline_message_id,
-                                           *args, **kwargs)
-        else:
-            return self.bot.set_game_score(chat_id=self.message.chat_id,
-                                           message_id=self.message.message_id,
-                                           *args, **kwargs)
+            return self.bot.set_game_score(
+                inline_message_id=self.inline_message_id,
+                user_id=user_id,
+                score=score,
+                force=force,
+                disable_edit_message=disable_edit_message,
+                timeout=timeout,
+                api_kwargs=api_kwargs,
+                chat_id=None,
+                message_id=None,
+            )
+        return self.message.set_game_score(
+            user_id=user_id,
+            score=score,
+            force=force,
+            disable_edit_message=disable_edit_message,
+            timeout=timeout,
+            api_kwargs=api_kwargs,
+        )
 
-    def get_game_high_scores(self, *args: Any, **kwargs: Any) -> List['GameHighScore']:
+    def get_game_high_scores(
+        self,
+        user_id: Union[int, str],
+        timeout: float = None,
+        api_kwargs: JSONDict = None,
+    ) -> List['GameHighScore']:
         """Shortcut for either::
 
-            bot.get_game_high_scores(chat_id=update.callback_query.message.chat_id,
-                                     message_id=update.callback_query.message.message_id,
-                                     reply_markup=reply_markup,
-                                     *args, **kwargs)
+            update.callback_query.message.get_game_high_score(*args, **kwargs)
 
         or::
 
             bot.get_game_high_scores(inline_message_id=update.callback_query.inline_message_id,
-                                     reply_markup=reply_markup,
                                      *args, **kwargs)
 
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.get_game_high_scores`.
+
         Returns:
             List[:class:`telegram.GameHighScore`]
 
         """
         if self.inline_message_id:
-            return self.bot.get_game_high_scores(inline_message_id=self.inline_message_id,
-                                                 *args, **kwargs)
-        else:
-            return self.bot.get_game_high_scores(chat_id=self.message.chat_id,
-                                                 message_id=self.message.message_id,
-                                                 *args, **kwargs)
+            return self.bot.get_game_high_scores(
+                inline_message_id=self.inline_message_id,
+                user_id=user_id,
+                timeout=timeout,
+                api_kwargs=api_kwargs,
+                chat_id=None,
+                message_id=None,
+            )
+        return self.message.get_game_high_scores(
+            user_id=user_id,
+            timeout=timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    def delete_message(
+        self,
+        timeout: float = None,
+        api_kwargs: JSONDict = None,
+    ) -> bool:
+        """Shortcut for::
+
+            update.callback_query.message.delete(*args, **kwargs)
+
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.delete_message`.
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+
+        """
+        return self.message.delete(
+            timeout=timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    def pin_message(
+        self,
+        disable_notification: bool = None,
+        timeout: float = None,
+        api_kwargs: JSONDict = None,
+    ) -> bool:
+        """Shortcut for::
+
+             bot.pin_chat_message(chat_id=message.chat_id,
+                                  message_id=message.message_id,
+                                  *args,
+                                  **kwargs)
+
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.pin_chat_message`.
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+
+        """
+        return self.message.pin(
+            disable_notification=disable_notification,
+            timeout=timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    def unpin_message(
+        self,
+        timeout: float = None,
+        api_kwargs: JSONDict = None,
+    ) -> bool:
+        """Shortcut for::
+
+             bot.unpin_chat_message(chat_id=message.chat_id,
+                                    message_id=message.message_id,
+                                    *args,
+                                    **kwargs)
+
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.unpin_chat_message`.
+
+        Returns:
+            :obj:`bool`: On success, :obj:`True` is returned.
+
+        """
+        return self.message.unpin(
+            timeout=timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    def copy_message(
+        self,
+        chat_id: Union[int, str],
+        caption: str = None,
+        parse_mode: str = None,
+        caption_entities: Union[Tuple['MessageEntity', ...], List['MessageEntity']] = None,
+        disable_notification: bool = False,
+        reply_to_message_id: Union[int, str] = None,
+        allow_sending_without_reply: bool = False,
+        reply_markup: ReplyMarkup = None,
+        timeout: float = None,
+        api_kwargs: JSONDict = None,
+    ) -> 'MessageId':
+        """Shortcut for::
+
+            update.callback_query.message.copy(
+                chat_id,
+                from_chat_id=update.message.chat_id,
+                message_id=update.message.message_id,
+                *args,
+                **kwargs)
+
+        For the documentation of the arguments, please see
+        :meth:`telegram.Bot.copy_message`.
+
+        Returns:
+            :class:`telegram.MessageId`: On success, returns the MessageId of the sent message.
+
+        """
+        return self.message.copy(
+            chat_id=chat_id,
+            caption=caption,
+            parse_mode=parse_mode,
+            caption_entities=caption_entities,
+            disable_notification=disable_notification,
+            reply_to_message_id=reply_to_message_id,
+            allow_sending_without_reply=allow_sending_without_reply,
+            reply_markup=reply_markup,
+            timeout=timeout,
+            api_kwargs=api_kwargs,
+        )
+
+    MAX_ANSWER_TEXT_LENGTH: ClassVar[int] = constants.MAX_ANSWER_CALLBACK_QUERY_TEXT_LENGTH
+    """
+    :const:`telegram.constants.MAX_ANSWER_CALLBACK_QUERY_TEXT_LENGTH`
+
+    .. versionadded:: 13.2
+    """

telegram/chataction.py

@@ -2,7 +2,7 @@
 # pylint: disable=R0903
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,28 +18,30 @@
 # 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 ChatAction."""
+from typing import ClassVar
+from telegram import constants
 
 
 class ChatAction:
     """Helper class to provide constants for different chat actions."""
 
-    FIND_LOCATION: str = 'find_location'
-    """:obj:`str`: 'find_location'"""
-    RECORD_AUDIO: str = 'record_audio'
-    """:obj:`str`: 'record_audio'"""
-    RECORD_VIDEO: str = 'record_video'
-    """:obj:`str`: 'record_video'"""
-    RECORD_VIDEO_NOTE: str = 'record_video_note'
-    """:obj:`str`: 'record_video_note'"""
-    TYPING: str = 'typing'
-    """:obj:`str`: 'typing'"""
-    UPLOAD_AUDIO: str = 'upload_audio'
-    """:obj:`str`: 'upload_audio'"""
-    UPLOAD_DOCUMENT: str = 'upload_document'
-    """:obj:`str`: 'upload_document'"""
-    UPLOAD_PHOTO: str = 'upload_photo'
-    """:obj:`str`: 'upload_photo'"""
-    UPLOAD_VIDEO: str = 'upload_video'
-    """:obj:`str`: 'upload_video'"""
-    UPLOAD_VIDEO_NOTE: str = 'upload_video_note'
-    """:obj:`str`: 'upload_video_note'"""
+    FIND_LOCATION: ClassVar[str] = constants.CHATACTION_FIND_LOCATION
+    """:const:`telegram.constants.CHATACTION_FIND_LOCATION`"""
+    RECORD_AUDIO: ClassVar[str] = constants.CHATACTION_RECORD_AUDIO
+    """:const:`telegram.constants.CHATACTION_RECORD_AUDIO`"""
+    RECORD_VIDEO: ClassVar[str] = constants.CHATACTION_RECORD_VIDEO
+    """:const:`telegram.constants.CHATACTION_RECORD_VIDEO`"""
+    RECORD_VIDEO_NOTE: ClassVar[str] = constants.CHATACTION_RECORD_VIDEO_NOTE
+    """:const:`telegram.constants.CHATACTION_RECORD_VIDEO_NOTE`"""
+    TYPING: ClassVar[str] = constants.CHATACTION_TYPING
+    """:const:`telegram.constants.CHATACTION_TYPING`"""
+    UPLOAD_AUDIO: ClassVar[str] = constants.CHATACTION_UPLOAD_AUDIO
+    """:const:`telegram.constants.CHATACTION_UPLOAD_AUDIO`"""
+    UPLOAD_DOCUMENT: ClassVar[str] = constants.CHATACTION_UPLOAD_DOCUMENT
+    """:const:`telegram.constants.CHATACTION_UPLOAD_DOCUMENT`"""
+    UPLOAD_PHOTO: ClassVar[str] = constants.CHATACTION_UPLOAD_PHOTO
+    """:const:`telegram.constants.CHATACTION_UPLOAD_PHOTO`"""
+    UPLOAD_VIDEO: ClassVar[str] = constants.CHATACTION_UPLOAD_VIDEO
+    """:const:`telegram.constants.CHATACTION_UPLOAD_VIDEO`"""
+    UPLOAD_VIDEO_NOTE: ClassVar[str] = constants.CHATACTION_UPLOAD_VIDEO_NOTE
+    """:const:`telegram.constants.CHATACTION_UPLOAD_VIDEO_NOTE`"""

telegram/chatlocation.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2021
+# 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 an object that represents a location to which a chat is connected."""
+
+from typing import TYPE_CHECKING, Any, Optional
+
+from telegram import TelegramObject
+from telegram.utils.types import JSONDict
+
+from .files.location import Location
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+
+class ChatLocation(TelegramObject):
+    """This object represents a location to which a chat is connected.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`location` is equal.
+
+    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.
+
+    Attributes:
+        location (:class:`telegram.Location`): The location to which the supergroup is connected.
+        address (:obj:`str`): Location address, as defined by the chat owner
+
+    """
+
+    def __init__(
+        self,
+        location: Location,
+        address: str,
+        **_kwargs: Any,
+    ):
+        self.location = location
+        self.address = address
+
+        self._id_attrs = (self.location,)
+
+    @classmethod
+    def de_json(cls, data: Optional[JSONDict], bot: 'Bot') -> Optional['ChatLocation']:
+        data = cls.parse_data(data)
+
+        if not data:
+            return None
+
+        data['location'] = Location.de_json(data.get('location'), bot)
+
+        return cls(bot=bot, **data)

telegram/chatmember.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,12 +18,12 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram ChatMember."""
 import datetime
+from typing import TYPE_CHECKING, Any, Optional, ClassVar
 
-from telegram import User, TelegramObject
-from telegram.utils.helpers import to_timestamp, from_timestamp
-
+from telegram import TelegramObject, User, constants
+from telegram.utils.helpers import from_timestamp, to_timestamp
 from telegram.utils.types import JSONDict
-from typing import Any, Optional, TYPE_CHECKING
+
 if TYPE_CHECKING:
     from telegram import Bot
 
@@ -34,46 +34,14 @@ 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.
 
-    Attributes:
-        user (:class:`telegram.User`): Information about the user.
-        status (:obj:`str`): The member's status in the chat.
-        custom_title (:obj:`str`): Optional. Custom title for owner and administrators.
-        until_date (:class:`datetime.datetime`): Optional. Date when restrictions will be lifted
-            for this user.
-        can_be_edited (:obj:`bool`): Optional. If the bot is allowed to edit administrator
-            privileges of that user.
-        can_change_info (:obj:`bool`): Optional. If the user can change the chat title, photo and
-            other settings.
-        can_post_messages (:obj:`bool`): Optional. If the administrator can post in the channel.
-        can_edit_messages (:obj:`bool`): Optional. If the administrator can edit messages of other
-            users.
-        can_delete_messages (:obj:`bool`): Optional. If the administrator can delete messages of
-            other users.
-        can_invite_users (:obj:`bool`): Optional. If the user can invite new users to the chat.
-        can_restrict_members (:obj:`bool`): Optional. If the administrator can restrict, ban or
-            unban chat members.
-        can_pin_messages (:obj:`bool`): Optional. If the user can pin messages.
-        can_promote_members (:obj:`bool`): Optional. If the administrator can add new
-            administrators.
-        is_member (:obj:`bool`): Optional. Restricted only. :obj:`True`, if the user is a member of
-            the chat at the moment of the request.
-        can_send_messages (:obj:`bool`): Optional. If the user can send text messages, contacts,
-            locations and venues.
-        can_send_media_messages (:obj:`bool`): Optional. If the user can send media messages,
-            implies can_send_messages.
-        can_send_polls (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to
-            send polls.
-        can_send_other_messages (:obj:`bool`): Optional. If the user can send animations, games,
-            stickers and use inline bots, implies can_send_media_messages.
-        can_add_web_page_previews (:obj:`bool`): Optional. If user may add web page previews to his
-            messages, implies can_send_media_messages
-
     Args:
         user (:class:`telegram.User`): Information about the user.
         status (:obj:`str`): The member's status in the chat. Can be 'creator', 'administrator',
             'member', 'restricted', 'left' or 'kicked'.
         custom_title (:obj:`str`, optional): Owner and administrators only.
             Custom title for this user.
+        is_anonymous (:obj:`bool`, optional): Owner and administrators only. :obj:`True`, if the
+            user's presence in the chat is hidden.
         until_date (:class:`datetime.datetime`, optional): Restricted and kicked only. Date when
             restrictions will be lifted for this user.
         can_be_edited (:obj:`bool`, optional): Administrators only. :obj:`True`, if the bot is
@@ -109,45 +77,88 @@ class ChatMember(TelegramObject):
         can_add_web_page_previews (:obj:`bool`, optional): Restricted only. :obj:`True`, if user
             may add web page previews to his messages.
 
-    """
-    ADMINISTRATOR: str = 'administrator'
-    """:obj:`str`: 'administrator'"""
-    CREATOR: str = 'creator'
-    """:obj:`str`: 'creator'"""
-    KICKED: str = 'kicked'
-    """:obj:`str`: 'kicked'"""
-    LEFT: str = 'left'
-    """:obj:`str`: 'left'"""
-    MEMBER: str = 'member'
-    """:obj:`str`: 'member'"""
-    RESTRICTED: str = 'restricted'
-    """:obj:`str`: 'restricted'"""
+    Attributes:
+        user (:class:`telegram.User`): Information about the user.
+        status (:obj:`str`): The member's status in the chat.
+        custom_title (:obj:`str`): Optional. Custom title for owner and administrators.
+        is_anonymous (:obj:`bool`): Optional. :obj:`True`, if the user's presence in the chat is
+            hidden.
+        until_date (:class:`datetime.datetime`): Optional. Date when restrictions will be lifted
+            for this user.
+        can_be_edited (:obj:`bool`): Optional. If the bot is allowed to edit administrator
+            privileges of that user.
+        can_change_info (:obj:`bool`): Optional. If the user can change the chat title, photo and
+            other settings.
+        can_post_messages (:obj:`bool`): Optional. If the administrator can post in the channel.
+        can_edit_messages (:obj:`bool`): Optional. If the administrator can edit messages of other
+            users.
+        can_delete_messages (:obj:`bool`): Optional. If the administrator can delete messages of
+            other users.
+        can_invite_users (:obj:`bool`): Optional. If the user can invite new users to the chat.
+        can_restrict_members (:obj:`bool`): Optional. If the administrator can restrict, ban or
+            unban chat members.
+        can_pin_messages (:obj:`bool`): Optional. If the user can pin messages.
+        can_promote_members (:obj:`bool`): Optional. If the administrator can add new
+            administrators.
+        is_member (:obj:`bool`): Optional. Restricted only. :obj:`True`, if the user is a member of
+            the chat at the moment of the request.
+        can_send_messages (:obj:`bool`): Optional. If the user can send text messages, contacts,
+            locations and venues.
+        can_send_media_messages (:obj:`bool`): Optional. If the user can send media messages,
+            implies can_send_messages.
+        can_send_polls (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to
+            send polls.
+        can_send_other_messages (:obj:`bool`): Optional. If the user can send animations, games,
+            stickers and use inline bots, implies can_send_media_messages.
+        can_add_web_page_previews (:obj:`bool`): Optional. If user may add web page previews to his
+            messages, implies can_send_media_messages
 
-    def __init__(self,
-                 user: User,
-                 status: str,
-                 until_date: datetime.datetime = None,
-                 can_be_edited: bool = None,
-                 can_change_info: bool = None,
-                 can_post_messages: bool = None,
-                 can_edit_messages: bool = None,
-                 can_delete_messages: bool = None,
-                 can_invite_users: bool = None,
-                 can_restrict_members: bool = None,
-                 can_pin_messages: bool = None,
-                 can_promote_members: bool = None,
-                 can_send_messages: bool = None,
-                 can_send_media_messages: bool = None,
-                 can_send_polls: bool = None,
-                 can_send_other_messages: bool = None,
-                 can_add_web_page_previews: bool = None,
-                 is_member: bool = None,
-                 custom_title: str = None,
-                 **kwargs: Any):
+    """
+
+    ADMINISTRATOR: ClassVar[str] = constants.CHATMEMBER_ADMINISTRATOR
+    """:const:`telegram.constants.CHATMEMBER_ADMINISTRATOR`"""
+    CREATOR: ClassVar[str] = constants.CHATMEMBER_CREATOR
+    """:const:`telegram.constants.CHATMEMBER_CREATOR`"""
+    KICKED: ClassVar[str] = constants.CHATMEMBER_KICKED
+    """:const:`telegram.constants.CHATMEMBER_KICKED`"""
+    LEFT: ClassVar[str] = constants.CHATMEMBER_LEFT
+    """:const:`telegram.constants.CHATMEMBER_LEFT`"""
+    MEMBER: ClassVar[str] = constants.CHATMEMBER_MEMBER
+    """:const:`telegram.constants.CHATMEMBER_MEMBER`"""
+    RESTRICTED: ClassVar[str] = constants.CHATMEMBER_RESTRICTED
+    """:const:`telegram.constants.CHATMEMBER_RESTRICTED`"""
+
+    def __init__(
+        self,
+        user: User,
+        status: str,
+        until_date: datetime.datetime = None,
+        can_be_edited: bool = None,
+        can_change_info: bool = None,
+        can_post_messages: bool = None,
+        can_edit_messages: bool = None,
+        can_delete_messages: bool = None,
+        can_invite_users: bool = None,
+        can_restrict_members: bool = None,
+        can_pin_messages: bool = None,
+        can_promote_members: bool = None,
+        can_send_messages: bool = None,
+        can_send_media_messages: bool = None,
+        can_send_polls: bool = None,
+        can_send_other_messages: bool = None,
+        can_add_web_page_previews: bool = None,
+        is_member: bool = None,
+        custom_title: str = None,
+        is_anonymous: bool = None,
+        **_kwargs: Any,
+    ):
         # Required
         self.user = user
         self.status = status
+
+        # Optionals
         self.custom_title = custom_title
+        self.is_anonymous = is_anonymous
         self.until_date = until_date
         self.can_be_edited = can_be_edited
         self.can_change_info = can_change_info

telegram/chatpermissions.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,9 +18,10 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram ChatPermission."""
 
-from telegram import TelegramObject
 from typing import Any
 
+from telegram import TelegramObject
+
 
 class ChatPermissions(TelegramObject):
     """Describes actions that a non-administrator user is allowed to take in a chat.
@@ -35,26 +36,6 @@ class ChatPermissions(TelegramObject):
         permissions that are set, but also sets all the others to :obj:`False`. However, since not
         documented, this behaviour may change unbeknown to PTB.
 
-    Attributes:
-        can_send_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to send text
-            messages, contacts, locations and venues.
-        can_send_media_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to
-            send audios, documents, photos, videos, video notes and voice notes, implies
-            :attr:`can_send_messages`.
-        can_send_polls (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to send polls,
-            implies :attr:`can_send_messages`.
-        can_send_other_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to
-            send animations, games, stickers and use inline bots, implies
-            :attr:`can_send_media_messages`.
-        can_add_web_page_previews (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to
-            add web page previews to their messages, implies :attr:`can_send_media_messages`.
-        can_change_info (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to change the
-            chat title, photo and other settings. Ignored in public supergroups.
-        can_invite_users (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to invite
-            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.
-
     Args:
         can_send_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed to send text
             messages, contacts, locations and venues.
@@ -75,18 +56,40 @@ class ChatPermissions(TelegramObject):
         can_pin_messages (:obj:`bool`, optional): :obj:`True`, if the user is allowed to pin
             messages. Ignored in public supergroups.
 
+    Attributes:
+        can_send_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to send text
+            messages, contacts, locations and venues.
+        can_send_media_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to
+            send audios, documents, photos, videos, video notes and voice notes, implies
+            :attr:`can_send_messages`.
+        can_send_polls (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to send polls,
+            implies :attr:`can_send_messages`.
+        can_send_other_messages (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to
+            send animations, games, stickers and use inline bots, implies
+            :attr:`can_send_media_messages`.
+        can_add_web_page_previews (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to
+            add web page previews to their messages, implies :attr:`can_send_media_messages`.
+        can_change_info (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to change the
+            chat title, photo and other settings. Ignored in public supergroups.
+        can_invite_users (:obj:`bool`): Optional. :obj:`True`, if the user is allowed to invite
+            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.
+
     """
 
-    def __init__(self,
-                 can_send_messages: bool = None,
-                 can_send_media_messages: bool = None,
-                 can_send_polls: bool = None,
-                 can_send_other_messages: bool = None,
-                 can_add_web_page_previews: bool = None,
-                 can_change_info: bool = None,
-                 can_invite_users: bool = None,
-                 can_pin_messages: bool = None,
-                 **kwargs: Any):
+    def __init__(
+        self,
+        can_send_messages: bool = None,
+        can_send_media_messages: bool = None,
+        can_send_polls: bool = None,
+        can_send_other_messages: bool = None,
+        can_add_web_page_previews: bool = None,
+        can_change_info: bool = None,
+        can_invite_users: bool = None,
+        can_pin_messages: bool = None,
+        **_kwargs: Any,
+    ):
         # Required
         self.can_send_messages = can_send_messages
         self.can_send_media_messages = can_send_media_messages
@@ -105,5 +108,5 @@ class ChatPermissions(TelegramObject):
             self.can_add_web_page_previews,
             self.can_change_info,
             self.can_invite_users,
-            self.can_pin_messages
+            self.can_pin_messages,
         )

telegram/choseninlineresult.py

@@ -1,8 +1,8 @@
 #!/usr/bin/env python
-# pylint: disable=R0902,R0912,R0913
+# pylint: disable=R0902,R0913
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -19,9 +19,11 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram ChosenInlineResult."""
 
-from telegram import TelegramObject, User, Location
+from typing import TYPE_CHECKING, Any, Optional
+
+from telegram import Location, TelegramObject, User
 from telegram.utils.types import JSONDict
-from typing import Any, Optional, TYPE_CHECKING
+
 if TYPE_CHECKING:
     from telegram import Bot
 
@@ -35,14 +37,9 @@ class ChosenInlineResult(TelegramObject):
     considered equal, if their :attr:`result_id` is equal.
 
     Note:
-        In Python `from` is a reserved word, use `from_user` instead.
-
-    Attributes:
-        result_id (:obj:`str`): The unique identifier for the result that was chosen.
-        from_user (:class:`telegram.User`): The user that chose the result.
-        location (:class:`telegram.Location`): Optional. Sender location.
-        inline_message_id (:obj:`str`): Optional. Identifier of the sent inline message.
-        query (:obj:`str`): The query that was used to obtain the result.
+        * In Python `from` is a reserved word, use `from_user` instead.
+        * It is necessary to enable inline feedback via `@Botfather <https://t.me/BotFather>`_ in
+          order to receive these objects in updates.
 
     Args:
         result_id (:obj:`str`): The unique identifier for the result that was chosen.
@@ -55,19 +52,24 @@ class ChosenInlineResult(TelegramObject):
         query (:obj:`str`): The query that was used to obtain the result.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
-    Note:
-        It is necessary to enable inline feedback via `@Botfather <https://t.me/BotFather>`_ in
-        order to receive these objects in updates.
+    Attributes:
+        result_id (:obj:`str`): The unique identifier for the result that was chosen.
+        from_user (:class:`telegram.User`): The user that chose the result.
+        location (:class:`telegram.Location`): Optional. Sender location.
+        inline_message_id (:obj:`str`): Optional. Identifier of the sent inline message.
+        query (:obj:`str`): The query that was used to obtain the result.
 
     """
 
-    def __init__(self,
-                 result_id: str,
-                 from_user: User,
-                 query: str,
-                 location: Location = None,
-                 inline_message_id: str = None,
-                 **kwargs: Any):
+    def __init__(
+        self,
+        result_id: str,
+        from_user: User,
+        query: str,
+        location: Location = None,
+        inline_message_id: str = None,
+        **_kwargs: Any,
+    ):
         # Required
         self.result_id = result_id
         self.from_user = from_user

telegram/constants.py

@@ -1,5 +1,5 @@
 # python-telegram-bot - a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # by the python-telegram-bot contributors <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -32,27 +32,207 @@ Attributes:
     MAX_MESSAGES_PER_SECOND (:obj:`int`): 30
     MAX_MESSAGES_PER_MINUTE_PER_GROUP (:obj:`int`): 20
     MAX_INLINE_QUERY_RESULTS (:obj:`int`): 50
+    MAX_ANSWER_CALLBACK_QUERY_TEXT_LENGTH (:obj:`int`): 200
+
+        .. versionadded:: 13.2
 
 The following constant have been found by experimentation:
 
 Attributes:
     MAX_MESSAGE_ENTITIES (:obj:`int`): 100 (Beyond this cap telegram will simply ignore further
         formatting styles)
+    ANONYMOUS_ADMIN_ID (:obj:`int`): ``1087968824`` (User id in groups for anonymous admin)
+    SERVICE_CHAT_ID (:obj:`int`): ``777000`` (Telegram service chat, that also acts as sender of
+        channel posts forwarded to discussion groups)
+
+The following constants are related to specific classes and are also available
+as attributes of those classes:
+
+:class:`telegram.Chat`:
+
+Attributes:
+    CHAT_PRIVATE (:obj:`str`): 'private'
+    CHAT_GROUP (:obj:`str`): 'group'
+    CHAT_SUPERGROUP (:obj:`str`): 'supergroup'
+    CHAT_CHANNEL (:obj:`str`): 'channel'
+
+:class:`telegram.ChatAction`:
+
+Attributes:
+    CHATACTION_FIND_LOCATION (:obj:`str`): 'find_location'
+    CHATACTION_RECORD_AUDIO (:obj:`str`): 'record_audio'
+    CHATACTION_RECORD_VIDEO (:obj:`str`): 'record_video'
+    CHATACTION_RECORD_VIDEO_NOTE (:obj:`str`): 'record_video_note'
+    CHATACTION_TYPING (:obj:`str`): 'typing'
+    CHATACTION_UPLOAD_AUDIO (:obj:`str`): 'upload_audio'
+    CHATACTION_UPLOAD_DOCUMENT (:obj:`str`): 'upload_document'
+    CHATACTION_UPLOAD_PHOTO (:obj:`str`): 'upload_photo'
+    CHATACTION_UPLOAD_VIDEO (:obj:`str`): 'upload_video'
+    CHATACTION_UPLOAD_VIDEO_NOTE (:obj:`str`): 'upload_video_note'
+
+:class:`telegram.ChatMember`:
+
+Attributes:
+    CHATMEMBER_ADMINISTRATOR (:obj:`str`): 'administrator'
+    CHATMEMBER_CREATOR (:obj:`str`): 'creator'
+    CHATMEMBER_KICKED (:obj:`str`): 'kicked'
+    CHATMEMBER_LEFT (:obj:`str`): 'left'
+    CHATMEMBER_MEMBER (:obj:`str`): 'member'
+    CHATMEMBER_RESTRICTED (:obj:`str`): 'restricted'
+
+:class:`telegram.Dice`:
+
+Attributes:
+    DICE_DICE (:obj:`str`): '🎲'
+    DICE_DARTS (:obj:`str`): '🎯'
+    DICE_BASKETBALL (:obj:`str`): '🏀'
+    DICE_FOOTBALL (:obj:`str`): '⚽'
+    DICE_SLOT_MACHINE (:obj:`str`): '🎰'
+    DICE_ALL_EMOJI (List[:obj:`str`]): List of all supported base emoji.
+
+:class:`telegram.MessageEntity`:
+
+Attributes:
+    MESSAGEENTITY_MENTION (:obj:`str`): 'mention'
+    MESSAGEENTITY_HASHTAG (:obj:`str`): 'hashtag'
+    MESSAGEENTITY_CASHTAG (:obj:`str`): 'cashtag'
+    MESSAGEENTITY_PHONE_NUMBER (:obj:`str`): 'phone_number'
+    MESSAGEENTITY_BOT_COMMAND (:obj:`str`): 'bot_command'
+    MESSAGEENTITY_URL (:obj:`str`): 'url'
+    MESSAGEENTITY_EMAIL (:obj:`str`): 'email'
+    MESSAGEENTITY_BOLD (:obj:`str`): 'bold'
+    MESSAGEENTITY_ITALIC (:obj:`str`): 'italic'
+    MESSAGEENTITY_CODE (:obj:`str`): 'code'
+    MESSAGEENTITY_PRE (:obj:`str`): 'pre'
+    MESSAGEENTITY_TEXT_LINK (:obj:`str`): 'text_link'
+    MESSAGEENTITY_TEXT_MENTION (:obj:`str`): 'text_mention'
+    MESSAGEENTITY_UNDERLINE (:obj:`str`): 'underline'
+    MESSAGEENTITY_STRIKETHROUGH (:obj:`str`): 'strikethrough'
+    MESSAGEENTITY_ALL_TYPES (List[:obj:`str`]): List of all the types of message entity.
+
+:class:`telegram.ParseMode`:
+
+Attributes:
+    PARSEMODE_MARKDOWN (:obj:`str`): 'Markdown'
+    PARSEMODE_MARKDOWN_V2 (:obj:`str`): 'MarkdownV2'
+    PARSEMODE_HTML (:obj:`str`): 'HTML'
+
+:class:`telegram.Poll`:
+
+Attributes:
+    POLL_REGULAR (:obj:`str`): 'regular'
+    POLL_QUIZ (:obj:`str`): 'quiz'
+    MAX_POLL_QUESTION_LENGTH (:obj:`int`): 300
+    MAX_POLL_OPTION_LENGTH (:obj:`int`): 100
+
+:class:`telegram.files.MaskPosition`:
+
+Attributes:
+    STICKER_FOREHEAD (:obj:`str`): 'forehead'
+    STICKER_EYES (:obj:`str`): 'eyes'
+    STICKER_MOUTH (:obj:`str`): 'mouth'
+    STICKER_CHIN (:obj:`str`): 'chin'
 
 """
 from typing import List
 
 MAX_MESSAGE_LENGTH: int = 4096
 MAX_CAPTION_LENGTH: int = 1024
+ANONYMOUS_ADMIN_ID: int = 1087968824
+SERVICE_CHAT_ID: int = 777000
 
 # constants above this line are tested
 
 SUPPORTED_WEBHOOK_PORTS: List[int] = [443, 80, 88, 8443]
-MAX_FILESIZE_DOWNLOAD: int = int(20E6)  # (20MB)
-MAX_FILESIZE_UPLOAD: int = int(50E6)  # (50MB)
-MAX_PHOTOSIZE_UPLOAD: int = int(10E6)  # (10MB)
+MAX_FILESIZE_DOWNLOAD: int = int(20e6)  # (20MB)
+MAX_FILESIZE_UPLOAD: int = int(50e6)  # (50MB)
+MAX_PHOTOSIZE_UPLOAD: int = int(10e6)  # (10MB)
 MAX_MESSAGES_PER_SECOND_PER_CHAT: int = 1
 MAX_MESSAGES_PER_SECOND: int = 30
 MAX_MESSAGES_PER_MINUTE_PER_GROUP: int = 20
 MAX_MESSAGE_ENTITIES: int = 100
 MAX_INLINE_QUERY_RESULTS: int = 50
+MAX_ANSWER_CALLBACK_QUERY_TEXT_LENGTH: int = 200
+
+CHAT_PRIVATE: str = 'private'
+CHAT_GROUP: str = 'group'
+CHAT_SUPERGROUP: str = 'supergroup'
+CHAT_CHANNEL: str = 'channel'
+
+CHATACTION_FIND_LOCATION: str = 'find_location'
+CHATACTION_RECORD_AUDIO: str = 'record_audio'
+CHATACTION_RECORD_VIDEO: str = 'record_video'
+CHATACTION_RECORD_VIDEO_NOTE: str = 'record_video_note'
+CHATACTION_TYPING: str = 'typing'
+CHATACTION_UPLOAD_AUDIO: str = 'upload_audio'
+CHATACTION_UPLOAD_DOCUMENT: str = 'upload_document'
+CHATACTION_UPLOAD_PHOTO: str = 'upload_photo'
+CHATACTION_UPLOAD_VIDEO: str = 'upload_video'
+CHATACTION_UPLOAD_VIDEO_NOTE: str = 'upload_video_note'
+
+CHATMEMBER_ADMINISTRATOR: str = 'administrator'
+CHATMEMBER_CREATOR: str = 'creator'
+CHATMEMBER_KICKED: str = 'kicked'
+CHATMEMBER_LEFT: str = 'left'
+CHATMEMBER_MEMBER: str = 'member'
+CHATMEMBER_RESTRICTED: str = 'restricted'
+
+DICE_DICE: str = '🎲'
+DICE_DARTS: str = '🎯'
+DICE_BASKETBALL: str = '🏀'
+DICE_FOOTBALL: str = '⚽'
+DICE_SLOT_MACHINE: str = '🎰'
+DICE_ALL_EMOJI: List[str] = [
+    DICE_DICE,
+    DICE_DARTS,
+    DICE_BASKETBALL,
+    DICE_FOOTBALL,
+    DICE_SLOT_MACHINE,
+]
+
+MESSAGEENTITY_MENTION: str = 'mention'
+MESSAGEENTITY_HASHTAG: str = 'hashtag'
+MESSAGEENTITY_CASHTAG: str = 'cashtag'
+MESSAGEENTITY_PHONE_NUMBER: str = 'phone_number'
+MESSAGEENTITY_BOT_COMMAND: str = 'bot_command'
+MESSAGEENTITY_URL: str = 'url'
+MESSAGEENTITY_EMAIL: str = 'email'
+MESSAGEENTITY_BOLD: str = 'bold'
+MESSAGEENTITY_ITALIC: str = 'italic'
+MESSAGEENTITY_CODE: str = 'code'
+MESSAGEENTITY_PRE: str = 'pre'
+MESSAGEENTITY_TEXT_LINK: str = 'text_link'
+MESSAGEENTITY_TEXT_MENTION: str = 'text_mention'
+MESSAGEENTITY_UNDERLINE: str = 'underline'
+MESSAGEENTITY_STRIKETHROUGH: str = 'strikethrough'
+MESSAGEENTITY_ALL_TYPES: List[str] = [
+    MESSAGEENTITY_MENTION,
+    MESSAGEENTITY_HASHTAG,
+    MESSAGEENTITY_CASHTAG,
+    MESSAGEENTITY_PHONE_NUMBER,
+    MESSAGEENTITY_BOT_COMMAND,
+    MESSAGEENTITY_URL,
+    MESSAGEENTITY_EMAIL,
+    MESSAGEENTITY_BOLD,
+    MESSAGEENTITY_ITALIC,
+    MESSAGEENTITY_CODE,
+    MESSAGEENTITY_PRE,
+    MESSAGEENTITY_TEXT_LINK,
+    MESSAGEENTITY_TEXT_MENTION,
+    MESSAGEENTITY_UNDERLINE,
+    MESSAGEENTITY_STRIKETHROUGH,
+]
+
+PARSEMODE_MARKDOWN: str = 'Markdown'
+PARSEMODE_MARKDOWN_V2: str = 'MarkdownV2'
+PARSEMODE_HTML: str = 'HTML'
+
+POLL_REGULAR: str = 'regular'
+POLL_QUIZ: str = 'quiz'
+MAX_POLL_QUESTION_LENGTH: int = 300
+MAX_POLL_OPTION_LENGTH: int = 100
+
+STICKER_FOREHEAD: str = 'forehead'
+STICKER_EYES: str = 'eyes'
+STICKER_MOUTH: str = 'mouth'
+STICKER_CHIN: str = 'chin'

telegram/dice.py

@@ -2,7 +2,7 @@
 # pylint: disable=R0903
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,8 +18,9 @@
 # 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 telegram import TelegramObject
-from typing import Any, List
+from typing import Any, List, ClassVar
+
+from telegram import TelegramObject, constants
 
 
 class Dice(TelegramObject):
@@ -40,26 +41,40 @@ class Dice(TelegramObject):
         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 "🎰", each value corresponds to a unique combination of symbols, which
+        can be found at our `wiki <https://git.io/JkeC6>`_. However, this behaviour is undocumented
+        and might be changed by Telegram.
+
+    Args:
+        value (:obj:`int`): Value of the dice. 1-6 for dice and darts, 1-5 for basketball and
+            football/soccer ball, 1-64 for slot machine.
+        emoji (:obj:`str`): Emoji on which the dice throw animation is based.
+
     Attributes:
         value (:obj:`int`): Value of the dice.
         emoji (:obj:`str`): Emoji on which the dice throw animation is based.
 
-    Args:
-        value (:obj:`int`): Value of the dice. 1-6 for dice and darts, 1-5 for basketball.
-        emoji (:obj:`str`): Emoji on which the dice throw animation is based.
     """
-    def __init__(self, value: int, emoji: str, **kwargs: Any):
+
+    def __init__(self, value: int, emoji: str, **_kwargs: Any):
         self.value = value
         self.emoji = emoji
 
         self._id_attrs = (self.value, self.emoji)
 
-    DICE: str = '🎲'
-    """:obj:`str`: '🎲'"""
-    DARTS: str = '🎯'
-    """:obj:`str`: '🎯'"""
-    BASKETBALL = '🏀'
-    """:obj:`str`: '🏀'"""
-    ALL_EMOJI: List[str] = [DICE, DARTS, BASKETBALL]
-    """List[:obj:`str`]: List of all supported base emoji. Currently :attr:`DICE`,
-    :attr:`DARTS` and :attr:`BASKETBALL`."""
+    DICE: ClassVar[str] = constants.DICE_DICE
+    """:const:`telegram.constants.DICE_DICE`"""
+    DARTS: ClassVar[str] = constants.DICE_DARTS
+    """:const:`telegram.constants.DICE_DARTS`"""
+    BASKETBALL: ClassVar[str] = constants.DICE_BASKETBALL
+    """:const:`telegram.constants.DICE_BASKETBALL`"""
+    FOOTBALL: ClassVar[str] = constants.DICE_FOOTBALL
+    """:const:`telegram.constants.DICE_FOOTBALL`"""
+    SLOT_MACHINE: ClassVar[str] = constants.DICE_SLOT_MACHINE
+    """:const:`telegram.constants.DICE_SLOT_MACHINE`"""
+    ALL_EMOJI: ClassVar[List[str]] = constants.DICE_ALL_EMOJI
+    """:const:`telegram.constants.DICE_ALL_EMOJI`"""

telegram/error.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -16,6 +16,7 @@
 #
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
+# pylint: disable=C0115
 """This module contains an object that represents Telegram errors."""
 from typing import Tuple
 
@@ -31,7 +32,7 @@ def _lstrip_str(in_s: str, lstr: str) -> str:
 
     """
     if in_s.startswith(lstr):
-        res = in_s[len(lstr):]
+        res = in_s[len(lstr) :]
     else:
         res = in_s
     return res
@@ -92,7 +93,7 @@ class ChatMigrated(TelegramError):
     """
 
     def __init__(self, new_chat_id: int):
-        super().__init__('Group migrated to supergroup. New chat id: {}'.format(new_chat_id))
+        super().__init__(f'Group migrated to supergroup. New chat id: {new_chat_id}')
         self.new_chat_id = new_chat_id
 
     def __reduce__(self) -> Tuple[type, Tuple[int]]:  # type: ignore[override]
@@ -107,7 +108,7 @@ class RetryAfter(TelegramError):
     """
 
     def __init__(self, retry_after: int):
-        super().__init__('Flood control exceeded. Retry in {} seconds'.format(float(retry_after)))
+        super().__init__(f'Flood control exceeded. Retry in {float(retry_after)} seconds')
         self.retry_after = float(retry_after)
 
     def __reduce__(self) -> Tuple[type, Tuple[float]]:  # type: ignore[override]
@@ -116,15 +117,12 @@ class RetryAfter(TelegramError):
 
 class Conflict(TelegramError):
     """
-        Raised when a long poll or webhook conflicts with another one.
+    Raised when a long poll or webhook conflicts with another one.
 
-        Args:
-            msg (:obj:`str`): The message from telegrams server.
+    Args:
+        msg (:obj:`str`): The message from telegrams server.
 
     """
 
-    def __init__(self, msg: str):
-        super().__init__(msg)
-
     def __reduce__(self) -> Tuple[type, Tuple[str]]:
         return self.__class__, (self.message,)

telegram/ext/__init__.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -45,11 +45,38 @@ from .pollanswerhandler import PollAnswerHandler
 from .pollhandler import PollHandler
 from .defaults import Defaults
 
-__all__ = ('Dispatcher', 'JobQueue', 'Job', 'Updater', 'CallbackQueryHandler',
-           'ChosenInlineResultHandler', 'CommandHandler', 'Handler', 'InlineQueryHandler',
-           'MessageHandler', 'BaseFilter', 'MessageFilter', 'UpdateFilter', 'Filters',
-           'RegexHandler', 'StringCommandHandler', 'StringRegexHandler', 'TypeHandler',
-           'ConversationHandler', 'PreCheckoutQueryHandler', 'ShippingQueryHandler',
-           'MessageQueue', 'DelayQueue', 'DispatcherHandlerStop', 'run_async', 'CallbackContext',
-           'BasePersistence', 'PicklePersistence', 'DictPersistence', 'PrefixHandler',
-           'PollAnswerHandler', 'PollHandler', 'Defaults')
+__all__ = (
+    'Dispatcher',
+    'JobQueue',
+    'Job',
+    'Updater',
+    'CallbackQueryHandler',
+    'ChosenInlineResultHandler',
+    'CommandHandler',
+    'Handler',
+    'InlineQueryHandler',
+    'MessageHandler',
+    'BaseFilter',
+    'MessageFilter',
+    'UpdateFilter',
+    'Filters',
+    'RegexHandler',
+    'StringCommandHandler',
+    'StringRegexHandler',
+    'TypeHandler',
+    'ConversationHandler',
+    'PreCheckoutQueryHandler',
+    'ShippingQueryHandler',
+    'MessageQueue',
+    'DelayQueue',
+    'DispatcherHandlerStop',
+    'run_async',
+    'CallbackContext',
+    'BasePersistence',
+    'PicklePersistence',
+    'DictPersistence',
+    'PrefixHandler',
+    'PollAnswerHandler',
+    'PollHandler',
+    'Defaults',
+)

telegram/ext/basepersistence.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -17,14 +17,13 @@
 # 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 the BasePersistence class."""
-
+import warnings
 from abc import ABC, abstractmethod
-from collections import defaultdict
 from copy import copy
+from typing import DefaultDict, Dict, Optional, Tuple, cast, ClassVar
 
 from telegram import Bot
 
-from typing import DefaultDict, Dict, Any, Tuple, Optional, cast
 from telegram.utils.types import ConversationDict
 
 
@@ -32,17 +31,20 @@ class BasePersistence(ABC):
     """Interface class for adding persistence to your bot.
     Subclass this object for different implementations of a persistent bot.
 
-    All relevant methods must be overwritten. This means:
+    All relevant methods must be overwritten. This includes:
 
-    * If :attr:`store_bot_data` is :obj:`True` you must overwrite :meth:`get_bot_data` and
-      :meth:`update_bot_data`.
-    * If :attr:`store_chat_data` is :obj:`True` you must overwrite :meth:`get_chat_data` and
-      :meth:`update_chat_data`.
-    * If :attr:`store_user_data` is :obj:`True` you must overwrite :meth:`get_user_data` and
-      :meth:`update_user_data`.
-    * If you want to store conversation data with :class:`telegram.ext.ConversationHandler`, you
-      must overwrite :meth:`get_conversations` and :meth:`update_conversation`.
-    * :meth:`flush` will be called when the bot is shutdown.
+    * :meth:`get_bot_data`
+    * :meth:`update_bot_data`
+    * :meth:`get_chat_data`
+    * :meth:`update_chat_data`
+    * :meth:`get_user_data`
+    * :meth:`update_user_data`
+    * :meth:`get_conversations`
+    * :meth:`update_conversation`
+    * :meth:`flush`
+
+    If you don't actually need one of those methods, a simple ``pass`` is enough. For example, if
+    ``store_bot_data=False``, you don't need :meth:`get_bot_data` and :meth:`update_bot_data`.
 
     Warning:
         Persistence will try to replace :class:`telegram.Bot` instances by :attr:`REPLACED_BOT` and
@@ -56,14 +58,6 @@ class BasePersistence(ABC):
          of the :meth:`update/get_*` methods, i.e. you don't need to worry about it while
          implementing a custom persistence subclass.
 
-    Attributes:
-        store_user_data (:obj:`bool`): Optional, Whether user_data should be saved by this
-            persistence class.
-        store_chat_data (:obj:`bool`): Optional. Whether chat_data should be saved by this
-            persistence class.
-        store_bot_data (:obj:`bool`): Optional. Whether bot_data should be saved by this
-            persistence class.
-
     Args:
         store_user_data (:obj:`bool`, optional): Whether user_data should be saved by this
             persistence class. Default is :obj:`True`.
@@ -71,9 +65,19 @@ class BasePersistence(ABC):
             persistence class. Default is :obj:`True` .
         store_bot_data (:obj:`bool`, optional): Whether bot_data should be saved by this
             persistence class. Default is :obj:`True` .
+
+    Attributes:
+        store_user_data (:obj:`bool`): Optional, Whether user_data should be saved by this
+            persistence class.
+        store_chat_data (:obj:`bool`): Optional. Whether chat_data should be saved by this
+            persistence class.
+        store_bot_data (:obj:`bool`): Optional. Whether bot_data should be saved by this
+            persistence class.
     """
 
-    def __new__(cls, *args: Any, **kwargs: Any) -> 'BasePersistence':
+    def __new__(
+        cls, *args: object, **kwargs: object  # pylint: disable=W0613
+    ) -> 'BasePersistence':
         instance = super().__new__(cls)
         get_user_data = instance.get_user_data
         get_chat_data = instance.get_chat_data
@@ -82,13 +86,13 @@ class BasePersistence(ABC):
         update_chat_data = instance.update_chat_data
         update_bot_data = instance.update_bot_data
 
-        def get_user_data_insert_bot() -> DefaultDict[int, Dict[Any, Any]]:
+        def get_user_data_insert_bot() -> DefaultDict[int, Dict[object, object]]:
             return instance.insert_bot(get_user_data())
 
-        def get_chat_data_insert_bot() -> DefaultDict[int, Dict[Any, Any]]:
+        def get_chat_data_insert_bot() -> DefaultDict[int, Dict[object, object]]:
             return instance.insert_bot(get_chat_data())
 
-        def get_bot_data_insert_bot() -> Dict[Any, Any]:
+        def get_bot_data_insert_bot() -> Dict[object, object]:
             return instance.insert_bot(get_bot_data())
 
         def update_user_data_replace_bot(user_id: int, data: Dict) -> None:
@@ -108,10 +112,12 @@ class BasePersistence(ABC):
         instance.update_bot_data = update_bot_data_replace_bot
         return instance
 
-    def __init__(self,
-                 store_user_data: bool = True,
-                 store_chat_data: bool = True,
-                 store_bot_data: bool = True):
+    def __init__(
+        self,
+        store_user_data: bool = True,
+        store_chat_data: bool = True,
+        store_bot_data: bool = True,
+    ):
         self.store_user_data = store_user_data
         self.store_chat_data = store_chat_data
         self.store_bot_data = store_bot_data
@@ -131,7 +137,7 @@ class BasePersistence(ABC):
         Replaces all instances of :class:`telegram.Bot` that occur within the passed object with
         :attr:`REPLACED_BOT`. Currently, this handles objects of type ``list``, ``tuple``, ``set``,
         ``frozenset``, ``dict``, ``defaultdict`` and objects that have a ``__dict__`` or
-        ``__slot__`` attribute.
+        ``__slot__`` attribute, excluding objects that can't be copied with `copy.copy`.
 
         Args:
             obj (:obj:`object`): The object
@@ -139,26 +145,67 @@ class BasePersistence(ABC):
         Returns:
             :obj:`obj`: Copy of the object with Bot instances replaced.
         """
-        if isinstance(obj, Bot):
-            return cls.REPLACED_BOT
-        if isinstance(obj, (list, tuple, set, frozenset)):
-            return obj.__class__(cls.replace_bot(item) for item in obj)
+        return cls._replace_bot(obj, {})
 
-        new_obj = copy(obj)
-        if isinstance(obj, (dict, defaultdict)):
+    @classmethod
+    def _replace_bot(cls, obj: object, memo: Dict[int, object]) -> object:  # pylint: disable=R0911
+        obj_id = id(obj)
+        if obj_id in memo:
+            return memo[obj_id]
+
+        if isinstance(obj, Bot):
+            memo[obj_id] = cls.REPLACED_BOT
+            return cls.REPLACED_BOT
+        if isinstance(obj, (list, set)):
+            # We copy the iterable here for thread safety, i.e. make sure the object we iterate
+            # over doesn't change its length during the iteration
+            temp_iterable = obj.copy()
+            new_iterable = obj.__class__(cls._replace_bot(item, memo) for item in temp_iterable)
+            memo[obj_id] = new_iterable
+            return new_iterable
+        if isinstance(obj, (tuple, frozenset)):
+            # tuples and frozensets are immutable so we don't need to worry about thread safety
+            new_immutable = obj.__class__(cls._replace_bot(item, memo) for item in obj)
+            memo[obj_id] = new_immutable
+            return new_immutable
+
+        try:
+            new_obj = copy(obj)
+            memo[obj_id] = new_obj
+        except Exception:
+            warnings.warn(
+                'BasePersistence.replace_bot does not handle objects that can not be copied. See '
+                'the docs of BasePersistence.replace_bot for more information.',
+                RuntimeWarning,
+            )
+            memo[obj_id] = obj
+            return obj
+
+        if isinstance(obj, dict):
+            # We handle dicts via copy(obj) so we don't have to make a
+            # difference between dict and defaultdict
             new_obj = cast(dict, new_obj)
+            # We can't iterate over obj.items() due to thread safety, i.e. the dicts length may
+            # change during the iteration
+            temp_dict = new_obj.copy()
             new_obj.clear()
-            for k, v in obj.items():
-                new_obj[cls.replace_bot(k)] = cls.replace_bot(v)
+            for k, val in temp_dict.items():
+                new_obj[cls._replace_bot(k, memo)] = cls._replace_bot(val, memo)
+            memo[obj_id] = new_obj
             return new_obj
         if hasattr(obj, '__dict__'):
             for attr_name, attr in new_obj.__dict__.items():
-                setattr(new_obj, attr_name, cls.replace_bot(attr))
+                setattr(new_obj, attr_name, cls._replace_bot(attr, memo))
+            memo[obj_id] = new_obj
             return new_obj
         if hasattr(obj, '__slots__'):
             for attr_name in new_obj.__slots__:
-                setattr(new_obj, attr_name,
-                        cls.replace_bot(cls.replace_bot(getattr(new_obj, attr_name))))
+                setattr(
+                    new_obj,
+                    attr_name,
+                    cls._replace_bot(cls._replace_bot(getattr(new_obj, attr_name), memo), memo),
+                )
+            memo[obj_id] = new_obj
             return new_obj
 
         return obj
@@ -168,7 +215,7 @@ class BasePersistence(ABC):
         Replaces all instances of :attr:`REPLACED_BOT` that occur within the passed object with
         :attr:`bot`. Currently, this handles objects of type ``list``, ``tuple``, ``set``,
         ``frozenset``, ``dict``, ``defaultdict`` and objects that have a ``__dict__`` or
-        ``__slot__`` attribute.
+        ``__slot__`` attribute, excluding objects that can't be copied with `copy.copy`.
 
         Args:
             obj (:obj:`object`): The object
@@ -176,35 +223,76 @@ class BasePersistence(ABC):
         Returns:
             :obj:`obj`: Copy of the object with Bot instances inserted.
         """
-        if isinstance(obj, Bot):
-            return self.bot
-        if obj == self.REPLACED_BOT:
-            return self.bot
-        if isinstance(obj, (list, tuple, set, frozenset)):
-            return obj.__class__(self.insert_bot(item) for item in obj)
+        return self._insert_bot(obj, {})
 
-        new_obj = copy(obj)
-        if isinstance(obj, (dict, defaultdict)):
+    def _insert_bot(self, obj: object, memo: Dict[int, object]) -> object:  # pylint: disable=R0911
+        obj_id = id(obj)
+        if obj_id in memo:
+            return memo[obj_id]
+
+        if isinstance(obj, Bot):
+            memo[obj_id] = self.bot
+            return self.bot
+        if isinstance(obj, str) and obj == self.REPLACED_BOT:
+            memo[obj_id] = self.bot
+            return self.bot
+        if isinstance(obj, (list, set)):
+            # We copy the iterable here for thread safety, i.e. make sure the object we iterate
+            # over doesn't change its length during the iteration
+            temp_iterable = obj.copy()
+            new_iterable = obj.__class__(self._insert_bot(item, memo) for item in temp_iterable)
+            memo[obj_id] = new_iterable
+            return new_iterable
+        if isinstance(obj, (tuple, frozenset)):
+            # tuples and frozensets are immutable so we don't need to worry about thread safety
+            new_immutable = obj.__class__(self._insert_bot(item, memo) for item in obj)
+            memo[obj_id] = new_immutable
+            return new_immutable
+
+        try:
+            new_obj = copy(obj)
+        except Exception:
+            warnings.warn(
+                'BasePersistence.insert_bot does not handle objects that can not be copied. See '
+                'the docs of BasePersistence.insert_bot for more information.',
+                RuntimeWarning,
+            )
+            memo[obj_id] = obj
+            return obj
+
+        if isinstance(obj, dict):
+            # We handle dicts via copy(obj) so we don't have to make a
+            # difference between dict and defaultdict
             new_obj = cast(dict, new_obj)
+            # We can't iterate over obj.items() due to thread safety, i.e. the dicts length may
+            # change during the iteration
+            temp_dict = new_obj.copy()
             new_obj.clear()
-            for k, v in obj.items():
-                new_obj[self.insert_bot(k)] = self.insert_bot(v)
+            for k, val in temp_dict.items():
+                new_obj[self._insert_bot(k, memo)] = self._insert_bot(val, memo)
+            memo[obj_id] = new_obj
             return new_obj
         if hasattr(obj, '__dict__'):
             for attr_name, attr in new_obj.__dict__.items():
-                setattr(new_obj, attr_name, self.insert_bot(attr))
+                setattr(new_obj, attr_name, self._insert_bot(attr, memo))
+            memo[obj_id] = new_obj
             return new_obj
         if hasattr(obj, '__slots__'):
             for attr_name in obj.__slots__:
-                setattr(new_obj, attr_name,
-                        self.insert_bot(self.insert_bot(getattr(new_obj, attr_name))))
+                setattr(
+                    new_obj,
+                    attr_name,
+                    self._insert_bot(self._insert_bot(getattr(new_obj, attr_name), memo), memo),
+                )
+            memo[obj_id] = new_obj
             return new_obj
+
         return obj
 
     @abstractmethod
-    def get_user_data(self) -> DefaultDict[int, Dict[Any, Any]]:
-        """"Will be called by :class:`telegram.ext.Dispatcher` upon creation with a
-        persistence object. It should return the user_data if stored, or an empty
+    def get_user_data(self) -> DefaultDict[int, Dict[object, object]]:
+        """ "Will be called by :class:`telegram.ext.Dispatcher` upon creation with a
+        persistence object. It should return the ``user_data`` if stored, or an empty
         ``defaultdict(dict)``.
 
         Returns:
@@ -212,9 +300,9 @@ class BasePersistence(ABC):
         """
 
     @abstractmethod
-    def get_chat_data(self) -> DefaultDict[int, Dict[Any, Any]]:
-        """"Will be called by :class:`telegram.ext.Dispatcher` upon creation with a
-        persistence object. It should return the chat_data if stored, or an empty
+    def get_chat_data(self) -> DefaultDict[int, Dict[object, object]]:
+        """ "Will be called by :class:`telegram.ext.Dispatcher` upon creation with a
+        persistence object. It should return the ``chat_data`` if stored, or an empty
         ``defaultdict(dict)``.
 
         Returns:
@@ -222,9 +310,9 @@ class BasePersistence(ABC):
         """
 
     @abstractmethod
-    def get_bot_data(self) -> Dict[Any, Any]:
-        """"Will be called by :class:`telegram.ext.Dispatcher` upon creation with a
-        persistence object. It should return the bot_data if stored, or an empty
+    def get_bot_data(self) -> Dict[object, object]:
+        """ "Will be called by :class:`telegram.ext.Dispatcher` upon creation with a
+        persistence object. It should return the ``bot_data`` if stored, or an empty
         :obj:`dict`.
 
         Returns:
@@ -233,7 +321,7 @@ class BasePersistence(ABC):
 
     @abstractmethod
     def get_conversations(self, name: str) -> ConversationDict:
-        """"Will be called by :class:`telegram.ext.Dispatcher` when a
+        """ "Will be called by :class:`telegram.ext.Dispatcher` when a
         :class:`telegram.ext.ConversationHandler` is added if
         :attr:`telegram.ext.ConversationHandler.persistent` is :obj:`True`.
         It should return the conversations for the handler with `name` or an empty :obj:`dict`
@@ -246,9 +334,9 @@ class BasePersistence(ABC):
         """
 
     @abstractmethod
-    def update_conversation(self,
-                            name: str, key: Tuple[int, ...],
-                            new_state: Optional[object]) -> None:
+    def update_conversation(
+        self, name: str, key: Tuple[int, ...], new_state: Optional[object]
+    ) -> None:
         """Will be called when a :attr:`telegram.ext.ConversationHandler.update_state`
         is called. This allows the storage of the new state in the persistence.
 
@@ -289,10 +377,8 @@ class BasePersistence(ABC):
 
     def flush(self) -> None:
         """Will be called by :class:`telegram.ext.Updater` upon receiving a stop signal. Gives the
-        persistence a chance to finish up saving or close a database connection gracefully. If this
-        is not of any importance just pass will be sufficient.
+        persistence a chance to finish up saving or close a database connection gracefully.
         """
-        pass
 
-    REPLACED_BOT = 'bot_instance_replaced_by_ptb_persistence'
+    REPLACED_BOT: ClassVar[str] = 'bot_instance_replaced_by_ptb_persistence'
     """:obj:`str`: Placeholder for :class:`telegram.Bot` instances replaced in saved data."""

telegram/ext/callbackcontext.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -16,11 +16,13 @@
 #
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
+# pylint: disable=R0201
 """This module contains the CallbackContext class."""
 from queue import Queue
-from typing import Dict, Any, Tuple, TYPE_CHECKING, Optional, Match, List, NoReturn, Union
+from typing import TYPE_CHECKING, Dict, List, Match, NoReturn, Optional, Tuple, Union
 
 from telegram import Update
+
 if TYPE_CHECKING:
     from telegram import Bot
     from telegram.ext import Dispatcher, Job, JobQueue
@@ -71,9 +73,8 @@ class CallbackContext:
             is handled by :class:`telegram.ext.CommandHandler`, :class:`telegram.ext.PrefixHandler`
             or :class:`telegram.ext.StringCommandHandler`. It contains a list of the words in the
             text after the command, using any whitespace string as a delimiter.
-        error (:class:`telegram.TelegramError`): Optional. The error that was raised.
-            Only present when passed to a error handler registered with
-            :attr:`telegram.ext.Dispatcher.add_error_handler`.
+        error (:obj:`Exception`): Optional. The error that was raised. Only present when passed
+            to a error handler registered with :attr:`telegram.ext.Dispatcher.add_error_handler`.
         async_args (List[:obj:`object`]): Optional. Positional arguments of the function that
             raised the error. Only present when the raising function was run asynchronously using
             :meth:`telegram.ext.Dispatcher.run_async`.
@@ -91,18 +92,19 @@ class CallbackContext:
             dispatcher (:class:`telegram.ext.Dispatcher`):
         """
         if not dispatcher.use_context:
-            raise ValueError('CallbackContext should not be used with a non context aware '
-                             'dispatcher!')
+            raise ValueError(
+                'CallbackContext should not be used with a non context aware ' 'dispatcher!'
+            )
         self._dispatcher = dispatcher
         self._bot_data = dispatcher.bot_data
-        self._chat_data: Optional[Dict[Any, Any]] = None
-        self._user_data: Optional[Dict[Any, Any]] = None
+        self._chat_data: Optional[Dict[object, object]] = None
+        self._user_data: Optional[Dict[object, object]] = None
         self.args: Optional[List[str]] = None
         self.matches: Optional[List[Match]] = None
         self.error: Optional[Exception] = None
         self.job: Optional['Job'] = None
         self.async_args: Optional[Union[List, Tuple]] = None
-        self.async_kwargs: Optional[Dict[str, Any]] = None
+        self.async_kwargs: Optional[Dict[str, object]] = None
 
     @property
     def dispatcher(self) -> 'Dispatcher':
@@ -114,35 +116,40 @@ class CallbackContext:
         return self._bot_data
 
     @bot_data.setter
-    def bot_data(self, value: Any) -> NoReturn:
-        raise AttributeError("You can not assign a new value to bot_data, see "
-                             "https://git.io/fjxKe")
+    def bot_data(self, value: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to bot_data, see " "https://git.io/fjxKe"
+        )
 
     @property
     def chat_data(self) -> Optional[Dict]:
         return self._chat_data
 
     @chat_data.setter
-    def chat_data(self, value: Any) -> NoReturn:
-        raise AttributeError("You can not assign a new value to chat_data, see "
-                             "https://git.io/fjxKe")
+    def chat_data(self, value: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to chat_data, see " "https://git.io/fjxKe"
+        )
 
     @property
     def user_data(self) -> Optional[Dict]:
         return self._user_data
 
     @user_data.setter
-    def user_data(self, value: Any) -> NoReturn:
-        raise AttributeError("You can not assign a new value to user_data, see "
-                             "https://git.io/fjxKe")
+    def user_data(self, value: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to user_data, see " "https://git.io/fjxKe"
+        )
 
     @classmethod
-    def from_error(cls,
-                   update: object,
-                   error: Exception,
-                   dispatcher: 'Dispatcher',
-                   async_args: Union[List, Tuple] = None,
-                   async_kwargs: Dict[str, Any] = None) -> 'CallbackContext':
+    def from_error(
+        cls,
+        update: object,
+        error: Exception,
+        dispatcher: 'Dispatcher',
+        async_args: Union[List, Tuple] = None,
+        async_kwargs: Dict[str, object] = None,
+    ) -> 'CallbackContext':
         self = cls.from_update(update, dispatcher)
         self.error = error
         self.async_args = async_args
@@ -158,9 +165,9 @@ class CallbackContext:
             user = update.effective_user
 
             if chat:
-                self._chat_data = dispatcher.chat_data[chat.id]
+                self._chat_data = dispatcher.chat_data[chat.id]  # pylint: disable=W0212
             if user:
-                self._user_data = dispatcher.user_data[user.id]
+                self._user_data = dispatcher.user_data[user.id]  # pylint: disable=W0212
         return self
 
     @classmethod
@@ -169,7 +176,7 @@ class CallbackContext:
         self.job = job
         return self
 
-    def update(self, data: Dict[str, Any]) -> None:
+    def update(self, data: Dict[str, object]) -> None:
         self.__dict__.update(data)
 
     @property

telegram/ext/callbackqueryhandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -19,13 +19,22 @@
 """This module contains the CallbackQueryHandler class."""
 
 import re
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    Dict,
+    Match,
+    Optional,
+    Pattern,
+    TypeVar,
+    Union,
+    cast,
+)
 
 from telegram import Update
-from .handler import Handler
+from telegram.utils.helpers import DefaultValue, DEFAULT_FALSE
 
-from telegram.utils.types import HandlerArg
-from typing import Callable, TYPE_CHECKING, Any, Optional, Union, TypeVar, Pattern, Match, Dict, \
-    cast
+from .handler import Handler
 
 if TYPE_CHECKING:
     from telegram.ext import CallbackContext, Dispatcher
@@ -33,29 +42,11 @@ if TYPE_CHECKING:
 RT = TypeVar('RT')
 
 
-class CallbackQueryHandler(Handler):
+class CallbackQueryHandler(Handler[Update]):
     """Handler class to handle Telegram callback queries. Optionally based on a regex.
 
     Read the documentation of the ``re`` module for more information.
 
-    Attributes:
-        callback (:obj:`callable`): The callback function for this handler.
-        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
-            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
-            the callback function.
-        pattern (:obj:`str` | `Pattern`): Optional. Regex pattern to test
-            :attr:`telegram.CallbackQuery.data` against.
-        pass_groups (:obj:`bool`): Determines whether ``groups`` will be passed to the
-            callback function.
-        pass_groupdict (:obj:`bool`): Determines whether ``groupdict``. will be passed to
-            the callback function.
-        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
-            the callback function.
-        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
-            the callback function.
-        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
-
     Note:
         :attr:`pass_user_data` and :attr:`pass_chat_data` determine whether a ``dict`` you
         can use to keep any data in will be sent to the :attr:`callback` function. Related to
@@ -108,25 +99,46 @@ class CallbackQueryHandler(Handler):
         run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
             Defaults to :obj:`False`.
 
+    Attributes:
+        callback (:obj:`callable`): The callback function for this handler.
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
+            passed to the callback function.
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
+            the callback function.
+        pattern (:obj:`str` | `Pattern`): Optional. Regex pattern to test
+            :attr:`telegram.CallbackQuery.data` against.
+        pass_groups (:obj:`bool`): Determines whether ``groups`` will be passed to the
+            callback function.
+        pass_groupdict (:obj:`bool`): Determines whether ``groupdict``. will be passed to
+            the callback function.
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
+            the callback function.
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
+            the callback function.
+        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
+
     """
 
-    def __init__(self,
-                 callback: Callable[[HandlerArg, 'CallbackContext'], RT],
-                 pass_update_queue: bool = False,
-                 pass_job_queue: bool = False,
-                 pattern: Union[str, Pattern] = None,
-                 pass_groups: bool = False,
-                 pass_groupdict: bool = False,
-                 pass_user_data: bool = False,
-                 pass_chat_data: bool = False,
-                 run_async: bool = False):
+    def __init__(
+        self,
+        callback: Callable[[Update, 'CallbackContext'], RT],
+        pass_update_queue: bool = False,
+        pass_job_queue: bool = False,
+        pattern: Union[str, Pattern] = None,
+        pass_groups: bool = False,
+        pass_groupdict: bool = False,
+        pass_user_data: bool = False,
+        pass_chat_data: bool = False,
+        run_async: Union[bool, DefaultValue] = DEFAULT_FALSE,
+    ):
         super().__init__(
             callback,
             pass_update_queue=pass_update_queue,
             pass_job_queue=pass_job_queue,
             pass_user_data=pass_user_data,
             pass_chat_data=pass_chat_data,
-            run_async=run_async)
+            run_async=run_async,
+        )
 
         if isinstance(pattern, str):
             pattern = re.compile(pattern)
@@ -135,11 +147,11 @@ class CallbackQueryHandler(Handler):
         self.pass_groups = pass_groups
         self.pass_groupdict = pass_groupdict
 
-    def check_update(self, update: HandlerArg) -> Optional[Union[bool, object]]:
+    def check_update(self, update: object) -> Optional[Union[bool, object]]:
         """Determines whether an update should be passed to this handlers :attr:`callback`.
 
         Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
 
         Returns:
             :obj:`bool`
@@ -155,10 +167,12 @@ class CallbackQueryHandler(Handler):
                 return True
         return None
 
-    def collect_optional_args(self,
-                              dispatcher: 'Dispatcher',
-                              update: HandlerArg = None,
-                              check_result: Union[bool, Match] = None) -> Dict[str, Any]:
+    def collect_optional_args(
+        self,
+        dispatcher: 'Dispatcher',
+        update: Update = None,
+        check_result: Union[bool, Match] = None,
+    ) -> Dict[str, object]:
         optional_args = super().collect_optional_args(dispatcher, update, check_result)
         if self.pattern:
             check_result = cast(Match, check_result)
@@ -168,11 +182,13 @@ class CallbackQueryHandler(Handler):
                 optional_args['groupdict'] = check_result.groupdict()
         return optional_args
 
-    def collect_additional_context(self,
-                                   context: 'CallbackContext',
-                                   update: HandlerArg,
-                                   dispatcher: 'Dispatcher',
-                                   check_result: Union[bool, Match]) -> None:
+    def collect_additional_context(
+        self,
+        context: 'CallbackContext',
+        update: Update,
+        dispatcher: 'Dispatcher',
+        check_result: Union[bool, Match],
+    ) -> None:
         if self.pattern:
             check_result = cast(Match, check_result)
             context.matches = [check_result]

telegram/ext/choseninlineresulthandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,29 +18,18 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the ChosenInlineResultHandler class."""
 
+from typing import Optional, TypeVar, Union
+
 from telegram import Update
+
 from .handler import Handler
 
-from telegram.utils.types import HandlerArg
-from typing import Optional, Union, TypeVar
 RT = TypeVar('RT')
 
 
-class ChosenInlineResultHandler(Handler):
+class ChosenInlineResultHandler(Handler[Update]):
     """Handler class to handle Telegram updates that contain a chosen inline result.
 
-    Attributes:
-        callback (:obj:`callable`): The callback function for this handler.
-        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
-            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
-            the callback function.
-        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
-            the callback function.
-        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
-            the callback function.
-        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
-
     Note:
         :attr:`pass_user_data` and :attr:`pass_chat_data` determine whether a ``dict`` you
         can use to keep any data in will be sent to the :attr:`callback` function. Related to
@@ -82,13 +71,25 @@ class ChosenInlineResultHandler(Handler):
         run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
             Defaults to :obj:`False`.
 
+    Attributes:
+        callback (:obj:`callable`): The callback function for this handler.
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
+            passed to the callback function.
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
+            the callback function.
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
+            the callback function.
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
+            the callback function.
+        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
+
     """
 
-    def check_update(self, update: HandlerArg) -> Optional[Union[bool, object]]:
+    def check_update(self, update: object) -> Optional[Union[bool, object]]:
         """Determines whether an update should be passed to this handlers :attr:`callback`.
 
         Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
 
         Returns:
             :obj:`bool`

telegram/ext/commandhandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -19,22 +19,23 @@
 """This module contains the CommandHandler and PrefixHandler classes."""
 import re
 import warnings
+from typing import TYPE_CHECKING, Callable, Dict, List, Optional, Tuple, TypeVar, Union
 
-from telegram.ext import Filters, BaseFilter
+from telegram import MessageEntity, Update
+from telegram.ext import BaseFilter, Filters
 from telegram.utils.deprecate import TelegramDeprecationWarning
+from telegram.utils.types import SLT
+from telegram.utils.helpers import DefaultValue, DEFAULT_FALSE
 
-from telegram import Update, MessageEntity
 from .handler import Handler
 
-from telegram.utils.types import HandlerArg
-from typing import Callable, TYPE_CHECKING, Any, Optional, Union, TypeVar, Dict, List, Tuple
 if TYPE_CHECKING:
     from telegram.ext import CallbackContext, Dispatcher
 
 RT = TypeVar('RT')
 
 
-class CommandHandler(Handler):
+class CommandHandler(Handler[Update]):
     """Handler class to handle Telegram commands.
 
     Commands are Telegram messages that start with ``/``, optionally followed by an ``@`` and the
@@ -48,27 +49,6 @@ class CommandHandler(Handler):
     Note:
         :class:`telegram.ext.CommandHandler` does *not* handle (edited) channel posts.
 
-    Attributes:
-        command (:obj:`str` | List[:obj:`str`]): The command or list of commands this handler
-            should listen for. Limitations are the same as described here
-            https://core.telegram.org/bots#commands
-        callback (:obj:`callable`): The callback function for this handler.
-        filters (:class:`telegram.ext.BaseFilter`): Optional. Only allow updates with these
-            Filters.
-        allow_edited (:obj:`bool`): Determines whether the handler should also accept
-            edited messages.
-        pass_args (:obj:`bool`): Determines whether the handler should be passed
-            ``args``.
-        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
-            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
-            the callback function.
-        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
-            the callback function.
-        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
-            the callback function.
-        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
-
     Note:
         :attr:`pass_user_data` and :attr:`pass_chat_data` determine whether a :obj:`dict` you
         can use to keep any data in will be sent to the :attr:`callback` function. Related to
@@ -83,9 +63,9 @@ class CommandHandler(Handler):
         attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
 
     Args:
-        command (:obj:`str` | List[:obj:`str`]): The command or list of commands this handler
-            should listen for. Limitations are the same as described here
-            https://core.telegram.org/bots#commands
+        command (:class:`telegram.utils.types.SLT[str]`):
+            The command or list of commands this handler should listen for.
+            Limitations are the same as described here https://core.telegram.org/bots#commands
         callback (:obj:`callable`): The callback function for this handler. Will be called when
             :attr:`check_update` has determined that an update should be processed by this handler.
             Callback signature for context based API:
@@ -128,26 +108,50 @@ class CommandHandler(Handler):
 
     Raises:
         ValueError - when command is too long or has illegal chars.
+
+    Attributes:
+        command (:class:`telegram.utils.types.SLT[str]`):
+            The command or list of commands this handler should listen for.
+            Limitations are the same as described here https://core.telegram.org/bots#commands
+        callback (:obj:`callable`): The callback function for this handler.
+        filters (:class:`telegram.ext.BaseFilter`): Optional. Only allow updates with these
+            Filters.
+        allow_edited (:obj:`bool`): Determines whether the handler should also accept
+            edited messages.
+        pass_args (:obj:`bool`): Determines whether the handler should be passed
+            ``args``.
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
+            passed to the callback function.
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
+            the callback function.
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
+            the callback function.
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
+            the callback function.
+        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
     """
 
-    def __init__(self,
-                 command: Union[str, List[str]],
-                 callback: Callable[[HandlerArg, 'CallbackContext'], RT],
-                 filters: BaseFilter = None,
-                 allow_edited: bool = None,
-                 pass_args: bool = False,
-                 pass_update_queue: bool = False,
-                 pass_job_queue: bool = False,
-                 pass_user_data: bool = False,
-                 pass_chat_data: bool = False,
-                 run_async: bool = False):
+    def __init__(
+        self,
+        command: SLT[str],
+        callback: Callable[[Update, 'CallbackContext'], RT],
+        filters: BaseFilter = None,
+        allow_edited: bool = None,
+        pass_args: bool = False,
+        pass_update_queue: bool = False,
+        pass_job_queue: bool = False,
+        pass_user_data: bool = False,
+        pass_chat_data: bool = False,
+        run_async: Union[bool, DefaultValue] = DEFAULT_FALSE,
+    ):
         super().__init__(
             callback,
             pass_update_queue=pass_update_queue,
             pass_job_queue=pass_job_queue,
             pass_user_data=pass_user_data,
             pass_chat_data=pass_chat_data,
-            run_async=run_async)
+            run_async=run_async,
+        )
 
         if isinstance(command, str):
             self.command = [command.lower()]
@@ -163,21 +167,22 @@ class CommandHandler(Handler):
             self.filters = Filters.update.messages
 
         if allow_edited is not None:
-            warnings.warn('allow_edited is deprecated. See https://git.io/fxJuV for more info',
-                          TelegramDeprecationWarning,
-                          stacklevel=2)
+            warnings.warn(
+                'allow_edited is deprecated. See https://git.io/fxJuV for more info',
+                TelegramDeprecationWarning,
+                stacklevel=2,
+            )
             if not allow_edited:
                 self.filters &= ~Filters.update.edited_message
         self.pass_args = pass_args
 
     def check_update(
-            self,
-            update: HandlerArg) -> Optional[Union[bool, Tuple[List[str],
-                                                              Optional[Union[bool, Dict]]]]]:
+        self, update: object
+    ) -> Optional[Union[bool, Tuple[List[str], Optional[Union[bool, Dict]]]]]:
         """Determines whether an update should be passed to this handlers :attr:`callback`.
 
         Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
 
         Returns:
             :obj:`list`: The list of args for the handler.
@@ -186,41 +191,48 @@ class CommandHandler(Handler):
         if isinstance(update, Update) and update.effective_message:
             message = update.effective_message
 
-            if (message.entities and message.entities[0].type == MessageEntity.BOT_COMMAND
-                    and message.entities[0].offset == 0 and message.text and message.bot):
-                command = message.text[1:message.entities[0].length]
+            if (
+                message.entities
+                and message.entities[0].type == MessageEntity.BOT_COMMAND
+                and message.entities[0].offset == 0
+                and message.text
+                and message.bot
+            ):
+                command = message.text[1 : message.entities[0].length]
                 args = message.text.split()[1:]
                 command_parts = command.split('@')
                 command_parts.append(message.bot.username)
 
-                if not (command_parts[0].lower() in self.command
-                        and command_parts[1].lower() == message.bot.username.lower()):
+                if not (
+                    command_parts[0].lower() in self.command
+                    and command_parts[1].lower() == message.bot.username.lower()
+                ):
                     return None
 
                 filter_result = self.filters(update)
                 if filter_result:
                     return args, filter_result
-                else:
-                    return False
+                return False
         return None
 
     def collect_optional_args(
-            self,
-            dispatcher: 'Dispatcher',
-            update: HandlerArg = None,
-            check_result: Optional[Union[bool, Tuple[List[str],
-                                                     Optional[bool]]]] = None) -> Dict[str, Any]:
+        self,
+        dispatcher: 'Dispatcher',
+        update: Update = None,
+        check_result: Optional[Union[bool, Tuple[List[str], Optional[bool]]]] = None,
+    ) -> Dict[str, object]:
         optional_args = super().collect_optional_args(dispatcher, update)
         if self.pass_args and isinstance(check_result, tuple):
             optional_args['args'] = check_result[0]
         return optional_args
 
     def collect_additional_context(
-            self,
-            context: 'CallbackContext',
-            update: HandlerArg,
-            dispatcher: 'Dispatcher',
-            check_result: Optional[Union[bool, Tuple[List[str], Optional[bool]]]]) -> None:
+        self,
+        context: 'CallbackContext',
+        update: Update,
+        dispatcher: 'Dispatcher',
+        check_result: Optional[Union[bool, Tuple[List[str], Optional[bool]]]],
+    ) -> None:
         if isinstance(check_result, tuple):
             context.args = check_result[0]
             if isinstance(check_result[1], dict):
@@ -257,9 +269,6 @@ class PrefixHandler(CommandHandler):
     use ~``Filters.update.edited_message``.
 
     Attributes:
-        prefix (:obj:`str` | List[:obj:`str`]): The prefix(es) that will precede :attr:`command`.
-        command (:obj:`str` | List[:obj:`str`]): The command or list of commands this handler
-            should listen for.
         callback (:obj:`callable`): The callback function for this handler.
         filters (:class:`telegram.ext.BaseFilter`): Optional. Only allow updates with these
             Filters.
@@ -289,9 +298,10 @@ class PrefixHandler(CommandHandler):
         attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
 
     Args:
-        prefix (:obj:`str` | List[:obj:`str`]): The prefix(es) that will precede :attr:`command`.
-        command (:obj:`str` | List[:obj:`str`]): The command or list of commands this handler
-            should listen for.
+        prefix (:class:`telegram.utils.types.SLT[str]`):
+            The prefix(es) that will precede :attr:`command`.
+        command (:class:`telegram.utils.types.SLT[str]`):
+            The command or list of commands this handler should listen for.
         callback (:obj:`callable`): The callback function for this handler. Will be called when
             :attr:`check_update` has determined that an update should be processed by this handler.
             Callback signature for context based API:
@@ -330,29 +340,36 @@ class PrefixHandler(CommandHandler):
 
     """
 
-    def __init__(self,
-                 prefix: Union[str, List[str]],
-                 command: Union[str, List[str]],
-                 callback: Callable[[HandlerArg, 'CallbackContext'], RT],
-                 filters: BaseFilter = None,
-                 pass_args: bool = False,
-                 pass_update_queue: bool = False,
-                 pass_job_queue: bool = False,
-                 pass_user_data: bool = False,
-                 pass_chat_data: bool = False,
-                 run_async: bool = False):
+    def __init__(
+        self,
+        prefix: SLT[str],
+        command: SLT[str],
+        callback: Callable[[Update, 'CallbackContext'], RT],
+        filters: BaseFilter = None,
+        pass_args: bool = False,
+        pass_update_queue: bool = False,
+        pass_job_queue: bool = False,
+        pass_user_data: bool = False,
+        pass_chat_data: bool = False,
+        run_async: Union[bool, DefaultValue] = DEFAULT_FALSE,
+    ):
 
         self._prefix: List[str] = list()
         self._command: List[str] = list()
         self._commands: List[str] = list()
 
         super().__init__(
-            'nocommand', callback, filters=filters, allow_edited=None, pass_args=pass_args,
+            'nocommand',
+            callback,
+            filters=filters,
+            allow_edited=None,
+            pass_args=pass_args,
             pass_update_queue=pass_update_queue,
             pass_job_queue=pass_job_queue,
             pass_user_data=pass_user_data,
             pass_chat_data=pass_chat_data,
-            run_async=run_async)
+            run_async=run_async,
+        )
 
         self.prefix = prefix  # type: ignore[assignment]
         self.command = command  # type: ignore[assignment]
@@ -360,6 +377,12 @@ class PrefixHandler(CommandHandler):
 
     @property
     def prefix(self) -> List[str]:
+        """
+        The prefixes that will precede :attr:`command`.
+
+        Returns:
+            List[:obj:`str`]
+        """
         return self._prefix
 
     @prefix.setter
@@ -372,6 +395,12 @@ class PrefixHandler(CommandHandler):
 
     @property  # type: ignore[override]
     def command(self) -> List[str]:  # type: ignore[override]
+        """
+        The list of commands this handler should listen for.
+
+        Returns:
+            List[:obj:`str`]
+        """
         return self._command
 
     @command.setter
@@ -385,12 +414,13 @@ class PrefixHandler(CommandHandler):
     def _build_commands(self) -> None:
         self._commands = [x.lower() + y.lower() for x in self.prefix for y in self.command]
 
-    def check_update(self, update: HandlerArg) -> Optional[Union[bool, Tuple[List[str],
-                                                                 Optional[Union[bool, Dict]]]]]:
+    def check_update(
+        self, update: object
+    ) -> Optional[Union[bool, Tuple[List[str], Optional[Union[bool, Dict]]]]]:
         """Determines whether an update should be passed to this handlers :attr:`callback`.
 
         Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
 
         Returns:
             :obj:`list`: The list of args for the handler.
@@ -406,16 +436,16 @@ class PrefixHandler(CommandHandler):
                 filter_result = self.filters(update)
                 if filter_result:
                     return text_list[1:], filter_result
-                else:
-                    return False
+                return False
         return None
 
     def collect_additional_context(
-            self,
-            context: 'CallbackContext',
-            update: HandlerArg,
-            dispatcher: 'Dispatcher',
-            check_result: Optional[Union[bool, Tuple[List[str], Optional[bool]]]]) -> None:
+        self,
+        context: 'CallbackContext',
+        update: Update,
+        dispatcher: 'Dispatcher',
+        check_result: Optional[Union[bool, Tuple[List[str], Optional[bool]]]],
+    ) -> None:
         if isinstance(check_result, tuple):
             context.args = check_result[0]
             if isinstance(check_result[1], dict):

telegram/ext/conversationhandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -16,20 +16,26 @@
 #
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
+# pylint: disable=R0201
 """This module contains the ConversationHandler."""
 
 import logging
 import warnings
 from threading import Lock
+from typing import TYPE_CHECKING, Dict, List, NoReturn, Optional, Tuple, cast, ClassVar
 
 from telegram import Update
-from telegram.ext import (Handler, CallbackQueryHandler, InlineQueryHandler,
-                          ChosenInlineResultHandler, CallbackContext, BasePersistence,
-                          DispatcherHandlerStop)
-from telegram.utils.promise import Promise
-
-from telegram.utils.types import ConversationDict, HandlerArg
-from typing import Dict, Any, List, Optional, Tuple, TYPE_CHECKING, cast, NoReturn
+from telegram.ext import (
+    BasePersistence,
+    CallbackContext,
+    CallbackQueryHandler,
+    ChosenInlineResultHandler,
+    DispatcherHandlerStop,
+    Handler,
+    InlineQueryHandler,
+)
+from telegram.ext.utils.promise import Promise
+from telegram.utils.types import ConversationDict
 
 if TYPE_CHECKING:
     from telegram.ext import Dispatcher, Job
@@ -37,21 +43,37 @@ CheckUpdateType = Optional[Tuple[Tuple[int, ...], Handler, object]]
 
 
 class _ConversationTimeoutContext:
-    def __init__(self,
-                 conversation_key: Tuple[int, ...],
-                 update: Update,
-                 dispatcher: 'Dispatcher',
-                 callback_context: Optional[CallbackContext]):
+    def __init__(
+        self,
+        conversation_key: Tuple[int, ...],
+        update: Update,
+        dispatcher: 'Dispatcher',
+        callback_context: Optional[CallbackContext],
+    ):
         self.conversation_key = conversation_key
         self.update = update
         self.dispatcher = dispatcher
         self.callback_context = callback_context
 
 
-class ConversationHandler(Handler):
+class ConversationHandler(Handler[Update]):
     """
-    A handler to hold a conversation with a single user by managing four collections of other
-    handlers.
+    A handler to hold a conversation with a single or multiple users through Telegram updates by
+    managing four collections of other handlers.
+
+    Note:
+        ``ConversationHandler`` will only accept updates that are (subclass-)instances of
+        :class:`telegram.Update`. This is, because depending on the :attr:`per_user` and
+        :attr:`per_chat` ``ConversationHandler`` relies on
+        :attr:`telegram.Update.effective_user` and/or :attr:`telegram.Update.effective_chat` in
+        order to determine which conversation an update should belong to. For ``per_message=True``,
+        ``ConversationHandler`` uses ``update.callback_query.message.message_id`` when
+        ``per_chat=True`` and ``update.callback_query.inline_message_id`` when ``per_chat=False``.
+        For a more detailed explanation, please see our `FAQ`_.
+
+        Finally, ``ConversationHandler``, does *not* handle (edited) channel posts.
+
+    .. _`FAQ`: https://git.io/JtcyU
 
     The first collection, a ``list`` named :attr:`entry_points`, is used to initiate the
     conversation, for example with a :class:`telegram.ext.CommandHandler` or
@@ -76,6 +98,8 @@ class ConversationHandler(Handler):
     the conversation ends immediately after the execution of this callback function.
     To end the conversation, the callback function must return :attr:`END` or ``-1``. To
     handle the conversation timeout, use handler :attr:`TIMEOUT` or ``-2``.
+    Finally, :class:`telegram.ext.DispatcherHandlerStop` can be used in conversations as described
+    in the corresponding documentation.
 
     Note:
         In each of the described collections of handlers, a handler may in turn be a
@@ -91,35 +115,6 @@ class ConversationHandler(Handler):
 
     .. _`examples`: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples
 
-    Attributes:
-        entry_points (List[:class:`telegram.ext.Handler`]): A list of ``Handler`` objects that can
-            trigger the start of the conversation.
-        states (Dict[:obj:`object`, List[:class:`telegram.ext.Handler`]]): A :obj:`dict` that
-            defines the different states of conversation a user can be in and one or more
-            associated ``Handler`` objects that should be used in that state.
-        fallbacks (List[:class:`telegram.ext.Handler`]): A list of handlers that might be used if
-            the user is in a conversation, but every handler for their current state returned
-            :obj:`False` on :attr:`check_update`.
-        allow_reentry (:obj:`bool`): Determines if a user can restart a conversation with
-            an entry point.
-        per_chat (:obj:`bool`): If the conversationkey should contain the Chat's ID.
-        per_user (:obj:`bool`): If the conversationkey should contain the User's ID.
-        per_message (:obj:`bool`): If the conversationkey should contain the Message's
-            ID.
-        conversation_timeout (:obj:`float` | :obj:`datetime.timedelta`): Optional. When this
-            handler is inactive more than this timeout (in seconds), it will be automatically
-            ended. If this value is 0 (default), there will be no timeout. When it's triggered, the
-            last received update and the corresponding ``context`` will be handled by ALL the
-            handler's who's :attr:`check_update` method returns :obj:`True` that are in the state
-            :attr:`ConversationHandler.TIMEOUT`.
-        name (:obj:`str`): Optional. The name for this conversationhandler. Required for
-            persistence
-        persistent (:obj:`bool`): Optional. If the conversations dict for this handler should be
-            saved. Name is required and persistence has to be set in :class:`telegram.ext.Updater`
-        map_to_parent (Dict[:obj:`object`, :obj:`object`]): Optional. A :obj:`dict` that can be
-            used to instruct a nested conversationhandler to transition into a mapped state on
-            its parent conversationhandler in place of a specified nested state.
-
     Args:
         entry_points (List[:class:`telegram.ext.Handler`]): A list of ``Handler`` objects that can
             trigger the start of the conversation. The first handler which :attr:`check_update`
@@ -155,32 +150,78 @@ class ConversationHandler(Handler):
         map_to_parent (Dict[:obj:`object`, :obj:`object`], optional): A :obj:`dict` that can be
             used to instruct a nested conversationhandler to transition into a mapped state on
             its parent conversationhandler in place of a specified nested state.
+        run_async (:obj:`bool`, optional): Pass :obj:`True` to *override* the
+            :attr:`Handler.run_async` setting of all handlers (in :attr:`entry_points`,
+            :attr:`states` and :attr:`fallbacks`).
+
+            Note:
+                If set to :obj:`True`, you should not pass a handler instance, that needs to be
+                run synchronously in another context.
+
+            .. versionadded:: 13.2
 
     Raises:
         ValueError
 
+    Attributes:
+        entry_points (List[:class:`telegram.ext.Handler`]): A list of ``Handler`` objects that can
+            trigger the start of the conversation.
+        states (Dict[:obj:`object`, List[:class:`telegram.ext.Handler`]]): A :obj:`dict` that
+            defines the different states of conversation a user can be in and one or more
+            associated ``Handler`` objects that should be used in that state.
+        fallbacks (List[:class:`telegram.ext.Handler`]): A list of handlers that might be used if
+            the user is in a conversation, but every handler for their current state returned
+            :obj:`False` on :attr:`check_update`.
+        allow_reentry (:obj:`bool`): Determines if a user can restart a conversation with
+            an entry point.
+        per_chat (:obj:`bool`): If the conversationkey should contain the Chat's ID.
+        per_user (:obj:`bool`): If the conversationkey should contain the User's ID.
+        per_message (:obj:`bool`): If the conversationkey should contain the Message's
+            ID.
+        conversation_timeout (:obj:`float` | :obj:`datetime.timedelta`): Optional. When this
+            handler is inactive more than this timeout (in seconds), it will be automatically
+            ended. If this value is 0 (default), there will be no timeout. When it's triggered, the
+            last received update and the corresponding ``context`` will be handled by ALL the
+            handler's who's :attr:`check_update` method returns :obj:`True` that are in the state
+            :attr:`ConversationHandler.TIMEOUT`.
+        name (:obj:`str`): Optional. The name for this conversationhandler. Required for
+            persistence
+        persistent (:obj:`bool`): Optional. If the conversations dict for this handler should be
+            saved. Name is required and persistence has to be set in :class:`telegram.ext.Updater`
+        map_to_parent (Dict[:obj:`object`, :obj:`object`]): Optional. A :obj:`dict` that can be
+            used to instruct a nested conversationhandler to transition into a mapped state on
+            its parent conversationhandler in place of a specified nested state.
+        run_async (:obj:`bool`): If :obj:`True`, will override the
+            :attr:`Handler.run_async` setting of all internal handlers on initialization.
+
+            .. versionadded:: 13.2
+
     """
-    END = -1
+
+    END: ClassVar[int] = -1
     """:obj:`int`: Used as a constant to return when a conversation is ended."""
-    TIMEOUT = -2
+    TIMEOUT: ClassVar[int] = -2
     """:obj:`int`: Used as a constant to handle state when a conversation is timed out."""
-    WAITING = -3
+    WAITING: ClassVar[int] = -3
     """:obj:`int`: Used as a constant to handle state when a conversation is still waiting on the
     previous ``@run_sync`` decorated running handler to finish."""
-
-    def __init__(self,
-                 entry_points: List[Handler],
-                 states: Dict[object, List[Handler]],
-                 fallbacks: List[Handler],
-                 allow_reentry: bool = False,
-                 per_chat: bool = True,
-                 per_user: bool = True,
-                 per_message: bool = False,
-                 conversation_timeout: int = None,
-                 name: str = None,
-                 persistent: bool = False,
-                 map_to_parent: Dict[object, object] = None):
-        self.run_async = False
+    # pylint: disable=W0231
+    def __init__(
+        self,
+        entry_points: List[Handler],
+        states: Dict[object, List[Handler]],
+        fallbacks: List[Handler],
+        allow_reentry: bool = False,
+        per_chat: bool = True,
+        per_user: bool = True,
+        per_message: bool = False,
+        conversation_timeout: int = None,
+        name: str = None,
+        persistent: bool = False,
+        map_to_parent: Dict[object, object] = None,
+        run_async: bool = False,
+    ):
+        self.run_async = run_async
 
         self._entry_points = entry_points
         self._states = states
@@ -211,10 +252,12 @@ class ConversationHandler(Handler):
             raise ValueError("'per_user', 'per_chat' and 'per_message' can't all be 'False'")
 
         if self.per_message and not self.per_chat:
-            warnings.warn("If 'per_message=True' is used, 'per_chat=True' should also be used, "
-                          "since message IDs are not globally unique.")
+            warnings.warn(
+                "If 'per_message=True' is used, 'per_chat=True' should also be used, "
+                "since message IDs are not globally unique."
+            )
 
-        all_handlers = list()
+        all_handlers: List[Handler] = list()
         all_handlers.extend(entry_points)
         all_handlers.extend(fallbacks)
 
@@ -224,30 +267,40 @@ class ConversationHandler(Handler):
         if self.per_message:
             for handler in all_handlers:
                 if not isinstance(handler, CallbackQueryHandler):
-                    warnings.warn("If 'per_message=True', all entry points and state handlers"
-                                  " must be 'CallbackQueryHandler', since no other handlers "
-                                  "have a message context.")
+                    warnings.warn(
+                        "If 'per_message=True', all entry points and state handlers"
+                        " must be 'CallbackQueryHandler', since no other handlers "
+                        "have a message context."
+                    )
                     break
         else:
             for handler in all_handlers:
                 if isinstance(handler, CallbackQueryHandler):
-                    warnings.warn("If 'per_message=False', 'CallbackQueryHandler' will not be "
-                                  "tracked for every message.")
+                    warnings.warn(
+                        "If 'per_message=False', 'CallbackQueryHandler' will not be "
+                        "tracked for every message."
+                    )
                     break
 
         if self.per_chat:
             for handler in all_handlers:
                 if isinstance(handler, (InlineQueryHandler, ChosenInlineResultHandler)):
-                    warnings.warn("If 'per_chat=True', 'InlineQueryHandler' can not be used, "
-                                  "since inline queries have no chat context.")
+                    warnings.warn(
+                        "If 'per_chat=True', 'InlineQueryHandler' can not be used, "
+                        "since inline queries have no chat context."
+                    )
                     break
 
+        if self.run_async:
+            for handler in all_handlers:
+                handler.run_async = True
+
     @property
     def entry_points(self) -> List[Handler]:
         return self._entry_points
 
     @entry_points.setter
-    def entry_points(self, value: Any) -> NoReturn:
+    def entry_points(self, value: object) -> NoReturn:
         raise ValueError('You can not assign a new value to entry_points after initialization.')
 
     @property
@@ -255,7 +308,7 @@ class ConversationHandler(Handler):
         return self._states
 
     @states.setter
-    def states(self, value: Any) -> NoReturn:
+    def states(self, value: object) -> NoReturn:
         raise ValueError('You can not assign a new value to states after initialization.')
 
     @property
@@ -263,7 +316,7 @@ class ConversationHandler(Handler):
         return self._fallbacks
 
     @fallbacks.setter
-    def fallbacks(self, value: Any) -> NoReturn:
+    def fallbacks(self, value: object) -> NoReturn:
         raise ValueError('You can not assign a new value to fallbacks after initialization.')
 
     @property
@@ -271,7 +324,7 @@ class ConversationHandler(Handler):
         return self._allow_reentry
 
     @allow_reentry.setter
-    def allow_reentry(self, value: Any) -> NoReturn:
+    def allow_reentry(self, value: object) -> NoReturn:
         raise ValueError('You can not assign a new value to allow_reentry after initialization.')
 
     @property
@@ -279,7 +332,7 @@ class ConversationHandler(Handler):
         return self._per_user
 
     @per_user.setter
-    def per_user(self, value: Any) -> NoReturn:
+    def per_user(self, value: object) -> NoReturn:
         raise ValueError('You can not assign a new value to per_user after initialization.')
 
     @property
@@ -287,7 +340,7 @@ class ConversationHandler(Handler):
         return self._per_chat
 
     @per_chat.setter
-    def per_chat(self, value: Any) -> NoReturn:
+    def per_chat(self, value: object) -> NoReturn:
         raise ValueError('You can not assign a new value to per_chat after initialization.')
 
     @property
@@ -295,7 +348,7 @@ class ConversationHandler(Handler):
         return self._per_message
 
     @per_message.setter
-    def per_message(self, value: Any) -> NoReturn:
+    def per_message(self, value: object) -> NoReturn:
         raise ValueError('You can not assign a new value to per_message after initialization.')
 
     @property
@@ -303,16 +356,17 @@ class ConversationHandler(Handler):
         return self._conversation_timeout
 
     @conversation_timeout.setter
-    def conversation_timeout(self, value: Any) -> NoReturn:
-        raise ValueError('You can not assign a new value to conversation_timeout after '
-                         'initialization.')
+    def conversation_timeout(self, value: object) -> NoReturn:
+        raise ValueError(
+            'You can not assign a new value to conversation_timeout after ' 'initialization.'
+        )
 
     @property
     def name(self) -> Optional[str]:
         return self._name
 
     @name.setter
-    def name(self, value: Any) -> NoReturn:
+    def name(self, value: object) -> NoReturn:
         raise ValueError('You can not assign a new value to name after initialization.')
 
     @property
@@ -320,7 +374,7 @@ class ConversationHandler(Handler):
         return self._map_to_parent
 
     @map_to_parent.setter
-    def map_to_parent(self, value: Any) -> NoReturn:
+    def map_to_parent(self, value: object) -> NoReturn:
         raise ValueError('You can not assign a new value to map_to_parent after initialization.')
 
     @property
@@ -362,29 +416,35 @@ class ConversationHandler(Handler):
             key.append(user.id)
 
         if self.per_message:
-            key.append(update.callback_query.inline_message_id  # type: ignore[union-attr]
-                       or update.callback_query.message.message_id)  # type: ignore[union-attr]
+            key.append(
+                update.callback_query.inline_message_id  # type: ignore[union-attr]
+                or update.callback_query.message.message_id  # type: ignore[union-attr]
+            )
 
         return tuple(key)
 
-    def check_update(self, update: HandlerArg) -> CheckUpdateType:
+    def check_update(self, update: object) -> CheckUpdateType:  # pylint: disable=R0911
         """
         Determines whether an update should be handled by this conversationhandler, and if so in
         which state the conversation currently is.
 
         Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
 
         Returns:
             :obj:`bool`
 
         """
+        if not isinstance(update, Update):
+            return None
         # Ignore messages in channels
-        if (not isinstance(update, Update)
-                or update.channel_post
-                or self.per_chat and not update.effective_chat
-                or self.per_message and not update.callback_query
-                or update.callback_query and self.per_chat and not update.callback_query.message):
+        if update.channel_post or update.edited_channel_post:
+            return None
+        if self.per_chat and not update.effective_chat:
+            return None
+        if self.per_message and not update.callback_query:
+            return None
+        if update.callback_query and self.per_chat and not update.callback_query.message:
             return None
 
         key = self._get_key(update)
@@ -402,7 +462,7 @@ class ConversationHandler(Handler):
                     res = res if res is not None else old_state
                 except Exception as exc:
                     self.logger.exception("Promise function raised exception")
-                    self.logger.exception("{}".format(exc))
+                    self.logger.exception("%s", exc)
                     res = old_state
                 finally:
                     if res is None and old_state is None:
@@ -418,7 +478,7 @@ class ConversationHandler(Handler):
                         return key, hdlr, check
                 return None
 
-        self.logger.debug('selecting conversation {} with state {}'.format(str(key), str(state)))
+        self.logger.debug('selecting conversation %s with state %s', str(key), str(state))
 
         handler = None
 
@@ -438,7 +498,7 @@ class ConversationHandler(Handler):
         if state is not None and not handler:
             handlers = self.states.get(state)
 
-            for candidate in (handlers or []):
+            for candidate in handlers or []:
                 check = candidate.check_update(update)
                 if check is not None and check is not False:
                     handler = candidate
@@ -457,11 +517,13 @@ class ConversationHandler(Handler):
 
         return key, handler, check  # type: ignore[return-value]
 
-    def handle_update(self,  # type: ignore[override]
-                      update: HandlerArg,
-                      dispatcher: 'Dispatcher',
-                      check_result: CheckUpdateType,
-                      context: CallbackContext = None) -> Optional[object]:
+    def handle_update(  # type: ignore[override]
+        self,
+        update: Update,
+        dispatcher: 'Dispatcher',
+        check_result: CheckUpdateType,
+        context: CallbackContext = None,
+    ) -> Optional[object]:
         """Send the update to the callback for the current state and Handler
 
         Args:
@@ -485,34 +547,34 @@ class ConversationHandler(Handler):
                 timeout_job.schedule_removal()
         try:
             new_state = handler.handle_update(update, dispatcher, check_result, context)
-        except DispatcherHandlerStop as e:
-            new_state = e.state
+        except DispatcherHandlerStop as exception:
+            new_state = exception.state
             raise_dp_handler_stop = True
         with self._timeout_jobs_lock:
             if self.conversation_timeout and new_state != self.END and dispatcher.job_queue:
                 # Add the new timeout job
                 self.timeout_jobs[conversation_key] = dispatcher.job_queue.run_once(
-                    self._trigger_timeout, self.conversation_timeout,  # type: ignore[arg-type]
-                    context=_ConversationTimeoutContext(conversation_key, update,
-                                                        dispatcher, context))
+                    self._trigger_timeout,  # type: ignore[arg-type]
+                    self.conversation_timeout,
+                    context=_ConversationTimeoutContext(
+                        conversation_key, update, dispatcher, context
+                    ),
+                )
 
         if isinstance(self.map_to_parent, dict) and new_state in self.map_to_parent:
             self.update_state(self.END, conversation_key)
             if raise_dp_handler_stop:
                 raise DispatcherHandlerStop(self.map_to_parent.get(new_state))
-            else:
-                return self.map_to_parent.get(new_state)
-        else:
-            self.update_state(new_state, conversation_key)
-            if raise_dp_handler_stop:
-                # Don't pass the new state here. If we're in a nested conversation, the parent is
-                # expecting None as return value.
-                raise DispatcherHandlerStop()
+            return self.map_to_parent.get(new_state)
+
+        self.update_state(new_state, conversation_key)
+        if raise_dp_handler_stop:
+            # Don't pass the new state here. If we're in a nested conversation, the parent is
+            # expecting None as return value.
+            raise DispatcherHandlerStop()
         return None
 
-    def update_state(self,
-                     new_state: object,
-                     key: Tuple[int, ...]) -> None:
+    def update_state(self, new_state: object, key: Tuple[int, ...]) -> None:
         if new_state == self.END:
             with self._conversations_lock:
                 if key in self.conversations:
@@ -525,8 +587,9 @@ class ConversationHandler(Handler):
             with self._conversations_lock:
                 self.conversations[key] = (self.conversations.get(key), new_state)
                 if self.persistent and self.persistence and self.name:
-                    self.persistence.update_conversation(self.name, key,
-                                                         (self.conversations.get(key), new_state))
+                    self.persistence.update_conversation(
+                        self.name, key, (self.conversations.get(key), new_state)
+                    )
 
         elif new_state is not None:
             with self._conversations_lock:
@@ -534,9 +597,7 @@ class ConversationHandler(Handler):
                 if self.persistent and self.persistence and self.name:
                     self.persistence.update_conversation(self.name, key, new_state)
 
-    def _trigger_timeout(self,
-                         context: _ConversationTimeoutContext,
-                         job: 'Job' = None) -> None:
+    def _trigger_timeout(self, context: _ConversationTimeoutContext, job: 'Job' = None) -> None:
         self.logger.debug('conversation timeout was triggered!')
 
         # Backward compatibility with bots that do not use CallbackContext
@@ -559,9 +620,12 @@ class ConversationHandler(Handler):
             check = handler.check_update(context.update)
             if check is not None and check is not False:
                 try:
-                    handler.handle_update(context.update, context.dispatcher, check,
-                                          callback_context)
+                    handler.handle_update(
+                        context.update, context.dispatcher, check, callback_context
+                    )
                 except DispatcherHandlerStop:
-                    self.logger.warning('DispatcherHandlerStop in TIMEOUT state of '
-                                        'ConversationHandler has no effect. Ignoring.')
+                    self.logger.warning(
+                        'DispatcherHandlerStop in TIMEOUT state of '
+                        'ConversationHandler has no effect. Ignoring.'
+                    )
         self.update_state(self.END, context.conversation_key)

telegram/ext/defaults.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2020
+# Copyright (C) 2020-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -16,9 +16,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/].
+# pylint: disable=R0201, E0401
 """This module contains the class Defaults, which allows to pass default values to Updater."""
+from typing import NoReturn, Optional, Union
+
 import pytz
-from typing import Union, Optional, Any, NoReturn
 
 from telegram.utils.helpers import DEFAULT_NONE, DefaultValue
 
@@ -26,22 +28,6 @@ from telegram.utils.helpers import DEFAULT_NONE, DefaultValue
 class Defaults:
     """Convenience Class to gather all parameters with a (user defined) default value
 
-    Attributes:
-        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
-            bold, italic, fixed-width text or URLs in your bot's message.
-        disable_notification (:obj:`bool`): Optional. Sends the message silently. Users will
-            receive a notification with no sound.
-        disable_web_page_preview (:obj:`bool`): Optional. Disables link previews for links in this
-            message.
-        timeout (:obj:`int` | :obj:`float`): Optional. If this value is specified, use it as the
-            read timeout from the server (instead of the one specified during creation of the
-            connection pool).
-        quote (:obj:`bool`): Optional. If set to :obj:`True`, the reply is sent as an actual reply
-            to the message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter will
-            be ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
-        tzinfo (:obj:`tzinfo`): A timezone to be used for all date(time) objects appearing
-            throughout PTB.
-
     Parameters:
         parse_mode (:obj:`str`, optional): Send Markdown or HTML, if you want Telegram apps to show
             bold, italic, fixed-width text or URLs in your bot's message.
@@ -49,6 +35,8 @@ class Defaults:
             receive a notification with no sound.
         disable_web_page_preview (:obj:`bool`, optional): Disables link previews for links in this
             message.
+        allow_sending_without_reply (:obj:`bool`, optional): Pass :obj:`True`, if the message
+            should be sent even if the specified replied-to message is not found.
         timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as the
             read timeout from the server (instead of the one specified during creation of the
             connection pool).
@@ -59,84 +47,155 @@ class Defaults:
             appearing throughout PTB, i.e. if a timezone naive date(time) object is passed
             somewhere, it will be assumed to be in ``tzinfo``. Must be a timezone provided by the
             ``pytz`` module. Defaults to UTC.
+        run_async (:obj:`bool`, optional): Default setting for the ``run_async`` parameter of
+            handlers and error handlers registered through :meth:`Dispatcher.add_handler` and
+            :meth:`Dispatcher.add_error_handler`. Defaults to :obj:`False`.
+
+    Attributes:
+        parse_mode (:obj:`str`): Optional. Send Markdown or HTML, if you want Telegram apps to show
+            bold, italic, fixed-width text or URLs in your bot's message.
+        disable_notification (:obj:`bool`): Optional. Sends the message silently. Users will
+            receive a notification with no sound.
+        disable_web_page_preview (:obj:`bool`): Optional. Disables link previews for links in this
+            message.
+        allow_sending_without_reply (:obj:`bool`): Optional. Pass :obj:`True`, if the message
+            should be sent even if the specified replied-to message is not found.
+        timeout (:obj:`int` | :obj:`float`): Optional. If this value is specified, use it as the
+            read timeout from the server (instead of the one specified during creation of the
+            connection pool).
+        quote (:obj:`bool`): Optional. If set to :obj:`True`, the reply is sent as an actual reply
+            to the message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter will
+            be ignored. Default: :obj:`True` in group chats and :obj:`False` in private chats.
+        tzinfo (:obj:`tzinfo`): A timezone to be used for all date(time) objects appearing
+            throughout PTB.
+        run_async (:obj:`bool`): Optional. Default setting for the ``run_async`` parameter of
+            handlers and error handlers registered through :meth:`Dispatcher.add_handler` and
+            :meth:`Dispatcher.add_error_handler`.
     """
-    def __init__(self,
-                 parse_mode: str = None,
-                 disable_notification: bool = None,
-                 disable_web_page_preview: bool = None,
-                 # Timeout needs special treatment, since the bot methods have two different
-                 # default values for timeout (None and 20s)
-                 timeout: Union[float, DefaultValue] = DEFAULT_NONE,
-                 quote: bool = None,
-                 tzinfo: pytz.BaseTzInfo = pytz.utc):
+
+    def __init__(
+        self,
+        parse_mode: str = None,
+        disable_notification: bool = None,
+        disable_web_page_preview: bool = None,
+        # Timeout needs special treatment, since the bot methods have two different
+        # default values for timeout (None and 20s)
+        timeout: Union[float, DefaultValue] = DEFAULT_NONE,
+        quote: bool = None,
+        tzinfo: pytz.BaseTzInfo = pytz.utc,
+        run_async: bool = False,
+        allow_sending_without_reply: bool = None,
+    ):
         self._parse_mode = parse_mode
         self._disable_notification = disable_notification
         self._disable_web_page_preview = disable_web_page_preview
+        self._allow_sending_without_reply = allow_sending_without_reply
         self._timeout = timeout
         self._quote = quote
         self._tzinfo = tzinfo
+        self._run_async = run_async
 
     @property
     def parse_mode(self) -> Optional[str]:
         return self._parse_mode
 
     @parse_mode.setter
-    def parse_mode(self, value: Any) -> NoReturn:
-        raise AttributeError("You can not assign a new value to defaults after because it would "
-                             "not have any effect.")
+    def parse_mode(self, value: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to defaults after because it would "
+            "not have any effect."
+        )
 
     @property
     def disable_notification(self) -> Optional[bool]:
         return self._disable_notification
 
     @disable_notification.setter
-    def disable_notification(self, value: Any) -> NoReturn:
-        raise AttributeError("You can not assign a new value to defaults after because it would "
-                             "not have any effect.")
+    def disable_notification(self, value: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to defaults after because it would "
+            "not have any effect."
+        )
 
     @property
     def disable_web_page_preview(self) -> Optional[bool]:
         return self._disable_web_page_preview
 
     @disable_web_page_preview.setter
-    def disable_web_page_preview(self, value: Any) -> NoReturn:
-        raise AttributeError("You can not assign a new value to defaults after because it would "
-                             "not have any effect.")
+    def disable_web_page_preview(self, value: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to defaults after because it would "
+            "not have any effect."
+        )
+
+    @property
+    def allow_sending_without_reply(self) -> Optional[bool]:
+        return self._allow_sending_without_reply
+
+    @allow_sending_without_reply.setter
+    def allow_sending_without_reply(self, value: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to defaults after because it would "
+            "not have any effect."
+        )
 
     @property
     def timeout(self) -> Union[float, DefaultValue]:
         return self._timeout
 
     @timeout.setter
-    def timeout(self, value: Any) -> NoReturn:
-        raise AttributeError("You can not assign a new value to defaults after because it would "
-                             "not have any effect.")
+    def timeout(self, value: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to defaults after because it would "
+            "not have any effect."
+        )
 
     @property
     def quote(self) -> Optional[bool]:
         return self._quote
 
     @quote.setter
-    def quote(self, value: Any) -> NoReturn:
-        raise AttributeError("You can not assign a new value to defaults after because it would "
-                             "not have any effect.")
+    def quote(self, value: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to defaults after because it would "
+            "not have any effect."
+        )
 
     @property
     def tzinfo(self) -> pytz.BaseTzInfo:
         return self._tzinfo
 
     @tzinfo.setter
-    def tzinfo(self, value: Any) -> NoReturn:
-        raise AttributeError("You can not assign a new value to defaults after because it would "
-                             "not have any effect.")
+    def tzinfo(self, value: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to defaults after because it would "
+            "not have any effect."
+        )
+
+    @property
+    def run_async(self) -> bool:
+        return self._run_async
+
+    @run_async.setter
+    def run_async(self, value: object) -> NoReturn:
+        raise AttributeError(
+            "You can not assign a new value to defaults after because it would "
+            "not have any effect."
+        )
 
     def __hash__(self) -> int:
-        return hash((self._parse_mode,
-                     self._disable_notification,
-                     self._disable_web_page_preview,
-                     self._timeout,
-                     self._quote,
-                     self._tzinfo))
+        return hash(
+            (
+                self._parse_mode,
+                self._disable_notification,
+                self._disable_web_page_preview,
+                self._allow_sending_without_reply,
+                self._timeout,
+                self._quote,
+                self._tzinfo,
+                self._run_async,
+            )
+        )
 
     def __eq__(self, other: object) -> bool:
         if isinstance(other, Defaults):

telegram/ext/dictpersistence.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -19,18 +19,21 @@
 """This module contains the DictPersistence class."""
 from copy import deepcopy
 
-from telegram.utils.helpers import decode_user_chat_data_from_json,\
-    decode_conversations_from_json, encode_conversations_to_json
+from typing import DefaultDict, Dict, Optional, Tuple
+from collections import defaultdict
+
+from telegram.utils.helpers import (
+    decode_conversations_from_json,
+    decode_user_chat_data_from_json,
+    encode_conversations_to_json,
+)
+from telegram.ext import BasePersistence
+from telegram.utils.types import ConversationDict
 
 try:
     import ujson as json
 except ImportError:
     import json  # type: ignore[no-redef]
-from collections import defaultdict
-from telegram.ext import BasePersistence
-
-from typing import DefaultDict, Dict, Any, Tuple, Optional
-from telegram.utils.types import ConversationDict
 
 
 class DictPersistence(BasePersistence):
@@ -51,14 +54,6 @@ class DictPersistence(BasePersistence):
         :meth:`telegram.ext.BasePersistence.replace_bot` and
         :meth:`telegram.ext.BasePersistence.insert_bot`.
 
-    Attributes:
-        store_user_data (:obj:`bool`): Whether user_data should be saved by this
-            persistence class.
-        store_chat_data (:obj:`bool`): Whether chat_data should be saved by this
-            persistence class.
-        store_bot_data (:obj:`bool`): Whether bot_data should be saved by this
-            persistence class.
-
     Args:
         store_user_data (:obj:`bool`, optional): Whether user_data should be saved by this
             persistence class. Default is :obj:`True`.
@@ -74,19 +69,31 @@ class DictPersistence(BasePersistence):
             bot_data on creating this persistence. Default is ``""``.
         conversations_json (:obj:`str`, optional): Json string that will be used to reconstruct
             conversation on creating this persistence. Default is ``""``.
+
+    Attributes:
+        store_user_data (:obj:`bool`): Whether user_data should be saved by this
+            persistence class.
+        store_chat_data (:obj:`bool`): Whether chat_data should be saved by this
+            persistence class.
+        store_bot_data (:obj:`bool`): Whether bot_data should be saved by this
+            persistence class.
     """
 
-    def __init__(self,
-                 store_user_data: bool = True,
-                 store_chat_data: bool = True,
-                 store_bot_data: bool = True,
-                 user_data_json: str = '',
-                 chat_data_json: str = '',
-                 bot_data_json: str = '',
-                 conversations_json: str = ''):
-        super().__init__(store_user_data=store_user_data,
-                         store_chat_data=store_chat_data,
-                         store_bot_data=store_bot_data)
+    def __init__(
+        self,
+        store_user_data: bool = True,
+        store_chat_data: bool = True,
+        store_bot_data: bool = True,
+        user_data_json: str = '',
+        chat_data_json: str = '',
+        bot_data_json: str = '',
+        conversations_json: str = '',
+    ):
+        super().__init__(
+            store_user_data=store_user_data,
+            store_chat_data=store_chat_data,
+            store_bot_data=store_bot_data,
+        )
         self._user_data = None
         self._chat_data = None
         self._bot_data = None
@@ -99,20 +106,20 @@ class DictPersistence(BasePersistence):
             try:
                 self._user_data = decode_user_chat_data_from_json(user_data_json)
                 self._user_data_json = user_data_json
-            except (ValueError, AttributeError):
-                raise TypeError("Unable to deserialize user_data_json. Not valid JSON")
+            except (ValueError, AttributeError) as exc:
+                raise TypeError("Unable to deserialize user_data_json. Not valid JSON") from exc
         if chat_data_json:
             try:
                 self._chat_data = decode_user_chat_data_from_json(chat_data_json)
                 self._chat_data_json = chat_data_json
-            except (ValueError, AttributeError):
-                raise TypeError("Unable to deserialize chat_data_json. Not valid JSON")
+            except (ValueError, AttributeError) as exc:
+                raise TypeError("Unable to deserialize chat_data_json. Not valid JSON") from exc
         if bot_data_json:
             try:
                 self._bot_data = json.loads(bot_data_json)
                 self._bot_data_json = bot_data_json
-            except (ValueError, AttributeError):
-                raise TypeError("Unable to deserialize bot_data_json. Not valid JSON")
+            except (ValueError, AttributeError) as exc:
+                raise TypeError("Unable to deserialize bot_data_json. Not valid JSON") from exc
             if not isinstance(self._bot_data, dict):
                 raise TypeError("bot_data_json must be serialized dict")
 
@@ -120,8 +127,10 @@ class DictPersistence(BasePersistence):
             try:
                 self._conversations = decode_conversations_from_json(conversations_json)
                 self._conversations_json = conversations_json
-            except (ValueError, AttributeError):
-                raise TypeError("Unable to deserialize conversations_json. Not valid JSON")
+            except (ValueError, AttributeError) as exc:
+                raise TypeError(
+                    "Unable to deserialize conversations_json. Not valid JSON"
+                ) from exc
 
     @property
     def user_data(self) -> Optional[DefaultDict[int, Dict]]:
@@ -133,8 +142,7 @@ class DictPersistence(BasePersistence):
         """:obj:`str`: The user_data serialized as a JSON-string."""
         if self._user_data_json:
             return self._user_data_json
-        else:
-            return json.dumps(self.user_data)
+        return json.dumps(self.user_data)
 
     @property
     def chat_data(self) -> Optional[DefaultDict[int, Dict]]:
@@ -146,8 +154,7 @@ class DictPersistence(BasePersistence):
         """:obj:`str`: The chat_data serialized as a JSON-string."""
         if self._chat_data_json:
             return self._chat_data_json
-        else:
-            return json.dumps(self.chat_data)
+        return json.dumps(self.chat_data)
 
     @property
     def bot_data(self) -> Optional[Dict]:
@@ -159,11 +166,10 @@ class DictPersistence(BasePersistence):
         """:obj:`str`: The bot_data serialized as a JSON-string."""
         if self._bot_data_json:
             return self._bot_data_json
-        else:
-            return json.dumps(self.bot_data)
+        return json.dumps(self.bot_data)
 
     @property
-    def conversations(self) -> Optional[Dict[str, Dict[Tuple, Any]]]:
+    def conversations(self) -> Optional[Dict[str, Dict[Tuple, object]]]:
         """:obj:`dict`: The conversations as a dict."""
         return self._conversations
 
@@ -172,10 +178,9 @@ class DictPersistence(BasePersistence):
         """:obj:`str`: The conversations serialized as a JSON-string."""
         if self._conversations_json:
             return self._conversations_json
-        else:
-            return encode_conversations_to_json(self.conversations)  # type: ignore[arg-type]
+        return encode_conversations_to_json(self.conversations)  # type: ignore[arg-type]
 
-    def get_user_data(self) -> DefaultDict[int, Dict[Any, Any]]:
+    def get_user_data(self) -> DefaultDict[int, Dict[object, object]]:
         """Returns the user_data created from the ``user_data_json`` or an empty
         :obj:`defaultdict`.
 
@@ -188,7 +193,7 @@ class DictPersistence(BasePersistence):
             self._user_data = defaultdict(dict)
         return deepcopy(self.user_data)  # type: ignore[arg-type]
 
-    def get_chat_data(self) -> DefaultDict[int, Dict[Any, Any]]:
+    def get_chat_data(self) -> DefaultDict[int, Dict[object, object]]:
         """Returns the chat_data created from the ``chat_data_json`` or an empty
         :obj:`defaultdict`.
 
@@ -201,7 +206,7 @@ class DictPersistence(BasePersistence):
             self._chat_data = defaultdict(dict)
         return deepcopy(self.chat_data)  # type: ignore[arg-type]
 
-    def get_bot_data(self) -> Dict[Any, Any]:
+    def get_bot_data(self) -> Dict[object, object]:
         """Returns the bot_data created from the ``bot_data_json`` or an empty :obj:`dict`.
 
         Returns:
@@ -226,9 +231,9 @@ class DictPersistence(BasePersistence):
             self._conversations = {}
         return self.conversations.get(name, {}).copy()  # type: ignore[union-attr]
 
-    def update_conversation(self,
-                            name: str, key: Tuple[int, ...],
-                            new_state: Optional[object]) -> None:
+    def update_conversation(
+        self, name: str, key: Tuple[int, ...], new_state: Optional[object]
+    ) -> None:
         """Will update the conversations for the given handler.
 
         Args:

telegram/ext/dispatcher.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -21,34 +21,32 @@
 import logging
 import warnings
 import weakref
-from functools import wraps
-from threading import Thread, Lock, Event, current_thread, BoundedSemaphore
-from time import sleep
-from uuid import uuid4
 from collections import defaultdict
-
-from queue import Queue, Empty
+from functools import wraps
+from queue import Empty, Queue
+from threading import BoundedSemaphore, Event, Lock, Thread, current_thread
+from time import sleep
+from typing import TYPE_CHECKING, Callable, DefaultDict, Dict, List, Optional, Set, Union
+from uuid import uuid4
 
 from telegram import TelegramError, Update
-from telegram.ext.handler import Handler
-from telegram.ext.callbackcontext import CallbackContext
-from telegram.utils.deprecate import TelegramDeprecationWarning
-from telegram.utils.promise import Promise
 from telegram.ext import BasePersistence
-
-from typing import Any, Callable, TYPE_CHECKING, Optional, Union, DefaultDict, Dict, List, Set
-
-from telegram.utils.types import HandlerArg
+from telegram.ext.callbackcontext import CallbackContext
+from telegram.ext.handler import Handler
+from telegram.utils.deprecate import TelegramDeprecationWarning
+from telegram.ext.utils.promise import Promise
+from telegram.utils.helpers import DefaultValue, DEFAULT_FALSE
 
 if TYPE_CHECKING:
     from telegram import Bot
     from telegram.ext import JobQueue
 
-DEFAULT_GROUP = 0
+DEFAULT_GROUP: int = 0
 
 
-def run_async(func: Callable[[Update, CallbackContext],
-                             Any]) -> Callable[[Update, CallbackContext], Any]:
+def run_async(
+    func: Callable[[Update, CallbackContext], object]
+) -> Callable[[Update, CallbackContext], object]:
     """
     Function decorator that will run the function in a new thread.
 
@@ -66,13 +64,16 @@ def run_async(func: Callable[[Update, CallbackContext],
     """
 
     @wraps(func)
-    def async_func(*args: Any, **kwargs: Any) -> Any:
-        warnings.warn('The @run_async decorator is deprecated. Use the `run_async` parameter of'
-                      '`Dispatcher.add_handler` or `Dispatcher.run_async` instead.',
-                      TelegramDeprecationWarning,
-                      stacklevel=2)
-        return Dispatcher.get_instance()._run_async(func, *args, update=None, error_handling=False,
-                                                    **kwargs)
+    def async_func(*args: object, **kwargs: object) -> object:
+        warnings.warn(
+            'The @run_async decorator is deprecated. Use the `run_async` parameter of '
+            'your Handler or `Dispatcher.run_async` instead.',
+            TelegramDeprecationWarning,
+            stacklevel=2,
+        )
+        return Dispatcher.get_instance()._run_async(  # pylint: disable=W0212
+            func, *args, update=None, error_handling=False, **kwargs
+        )
 
     return async_func
 
@@ -96,6 +97,7 @@ class DispatcherHandlerStop(Exception):
     Args:
         state (:obj:`object`, optional): The next state of the conversation.
     """
+
     def __init__(self, state: object = None) -> None:
         super().__init__()
         self.state = state
@@ -104,19 +106,6 @@ class DispatcherHandlerStop(Exception):
 class Dispatcher:
     """This class dispatches all kinds of updates to its registered handlers.
 
-    Attributes:
-        bot (:class:`telegram.Bot`): The bot object that should be passed to the handlers.
-        update_queue (:obj:`Queue`): The synchronized queue that will contain the updates.
-        job_queue (:class:`telegram.ext.JobQueue`): Optional. The :class:`telegram.ext.JobQueue`
-            instance to pass onto handler callbacks.
-        workers (:obj:`int`, optional): Number of maximum concurrent worker threads for the
-            ``@run_async`` decorator and :meth:`run_async`.
-        user_data (:obj:`defaultdict`): A dictionary handlers can use to store data for the user.
-        chat_data (:obj:`defaultdict`): A dictionary handlers can use to store data for the chat.
-        bot_data (:obj:`dict`): A dictionary handlers can use to store data for the bot.
-        persistence (:class:`telegram.ext.BasePersistence`): Optional. The persistence class to
-            store data that should be persistent over restarts.
-
     Args:
         bot (:class:`telegram.Bot`): The bot object that should be passed to the handlers.
         update_queue (:obj:`Queue`): The synchronized queue that will contain the updates.
@@ -130,6 +119,19 @@ class Dispatcher:
             API (ignored if `dispatcher` argument is used). Defaults to :obj:`True`.
             **New users**: set this to :obj:`True`.
 
+    Attributes:
+        bot (:class:`telegram.Bot`): The bot object that should be passed to the handlers.
+        update_queue (:obj:`Queue`): The synchronized queue that will contain the updates.
+        job_queue (:class:`telegram.ext.JobQueue`): Optional. The :class:`telegram.ext.JobQueue`
+            instance to pass onto handler callbacks.
+        workers (:obj:`int`, optional): Number of maximum concurrent worker threads for the
+            ``@run_async`` decorator and :meth:`run_async`.
+        user_data (:obj:`defaultdict`): A dictionary handlers can use to store data for the user.
+        chat_data (:obj:`defaultdict`): A dictionary handlers can use to store data for the chat.
+        bot_data (:obj:`dict`): A dictionary handlers can use to store data for the bot.
+        persistence (:class:`telegram.ext.BasePersistence`): Optional. The persistence class to
+            store data that should be persistent over restarts.
+
     """
 
     __singleton_lock = Lock()
@@ -137,14 +139,16 @@ class Dispatcher:
     __singleton = None
     logger = logging.getLogger(__name__)
 
-    def __init__(self,
-                 bot: 'Bot',
-                 update_queue: Queue,
-                 workers: int = 4,
-                 exception_event: Event = None,
-                 job_queue: 'JobQueue' = None,
-                 persistence: BasePersistence = None,
-                 use_context: bool = True):
+    def __init__(
+        self,
+        bot: 'Bot',
+        update_queue: Queue,
+        workers: int = 4,
+        exception_event: Event = None,
+        job_queue: 'JobQueue' = None,
+        persistence: BasePersistence = None,
+        use_context: bool = True,
+    ):
         self.bot = bot
         self.update_queue = update_queue
         self.job_queue = job_queue
@@ -152,11 +156,14 @@ class Dispatcher:
         self.use_context = use_context
 
         if not use_context:
-            warnings.warn('Old Handler API is deprecated - see https://git.io/fxJuV for details',
-                          TelegramDeprecationWarning, stacklevel=3)
+            warnings.warn(
+                'Old Handler API is deprecated - see https://git.io/fxJuV for details',
+                TelegramDeprecationWarning,
+                stacklevel=3,
+            )
 
-        self.user_data: DefaultDict[int, Dict[Any, Any]] = defaultdict(dict)
-        self.chat_data: DefaultDict[int, Dict[Any, Any]] = defaultdict(dict)
+        self.user_data: DefaultDict[int, Dict[object, object]] = defaultdict(dict)
+        self.chat_data: DefaultDict[int, Dict[object, object]] = defaultdict(dict)
         self.bot_data = {}
         self.persistence: Optional[BasePersistence] = None
         self._update_persistence_lock = Lock()
@@ -184,7 +191,7 @@ class Dispatcher:
         """Dict[:obj:`int`, List[:class:`telegram.ext.Handler`]]: Holds the handlers per group."""
         self.groups: List[int] = []
         """List[:obj:`int`]: A list with all groups."""
-        self.error_handlers: Dict[Callable, bool] = {}
+        self.error_handlers: Dict[Callable, Union[bool, DefaultValue]] = {}
         """Dict[:obj:`callable`, :obj:`bool`]: A dict, where the keys are error handlers and the
         values indicate whether they are to be run asynchronously."""
 
@@ -208,11 +215,10 @@ class Dispatcher:
         return self.__exception_event
 
     def _init_async_threads(self, base_name: str, workers: int) -> None:
-        base_name = '{}_'.format(base_name) if base_name else ''
+        base_name = f'{base_name}_' if base_name else ''
 
         for i in range(workers):
-            thread = Thread(target=self._pooled, name='Bot:{}:worker:{}{}'.format(self.bot.id,
-                                                                                  base_name, i))
+            thread = Thread(target=self._pooled, name=f'Bot:{self.bot.id}:worker:{base_name}{i}')
             self.__async_threads.add(thread)
             thread.start()
 
@@ -234,9 +240,7 @@ class Dispatcher:
         """
         if cls.__singleton is not None:
             return cls.__singleton()  # type: ignore[return-value] # pylint: disable=not-callable
-        else:
-            raise RuntimeError('{} not initialized or multiple instances exist'.format(
-                cls.__name__))
+        raise RuntimeError(f'{cls.__name__} not initialized or multiple instances exist')
 
     def _pooled(self) -> None:
         thr_name = current_thread().getName()
@@ -245,8 +249,9 @@ class Dispatcher:
 
             # If unpacking fails, the thread pool is being closed from Updater._join_async_threads
             if not isinstance(promise, Promise):
-                self.logger.debug("Closing run_async thread %s/%d", thr_name,
-                                  len(self.__async_threads))
+                self.logger.debug(
+                    "Closing run_async thread %s/%d", thr_name, len(self.__async_threads)
+                )
                 break
 
             promise.run()
@@ -258,7 +263,8 @@ class Dispatcher:
             if isinstance(promise.exception, DispatcherHandlerStop):
                 self.logger.warning(
                     'DispatcherHandlerStop is not supported with async functions; func: %s',
-                    promise.pooled_function.__name__)
+                    promise.pooled_function.__name__,
+                )
                 continue
 
             # Avoid infinite recursion of error handlers.
@@ -280,11 +286,9 @@ class Dispatcher:
             except Exception:
                 self.logger.exception('An uncaught error was raised while handling the error.')
 
-    def run_async(self,
-                  func: Callable[..., Any],
-                  *args: Any,
-                  update: HandlerArg = None,
-                  **kwargs: Any) -> Promise:
+    def run_async(
+        self, func: Callable[..., object], *args: object, update: object = None, **kwargs: object
+    ) -> Promise:
         """
         Queue a function (with given args/kwargs) to be run asynchronously. Exceptions raised
         by the function will be handled by the error handlers registered with
@@ -299,9 +303,9 @@ class Dispatcher:
         Args:
             func (:obj:`callable`): The function to run in the thread.
             *args (:obj:`tuple`, optional): Arguments to ``func``.
-            update (:class:`telegram.Update`, optional): The update associated with the functions
-                call. If passed, it will be available in the error handlers, in case an exception
-                is raised by :attr:`func`.
+            update (:class:`telegram.Update` | :obj:`object`, optional): The update associated with
+                the functions call. If passed, it will be available in the error handlers, in case
+                an exception is raised by :attr:`func`.
             **kwargs (:obj:`dict`, optional): Keyword arguments to ``func``.
 
         Returns:
@@ -310,12 +314,14 @@ class Dispatcher:
         """
         return self._run_async(func, *args, update=update, error_handling=True, **kwargs)
 
-    def _run_async(self,
-                   func: Callable[..., Any],
-                   *args: Any,
-                   update: HandlerArg = None,
-                   error_handling: bool = True,
-                   **kwargs: Any) -> Promise:
+    def _run_async(
+        self,
+        func: Callable[..., object],
+        *args: object,
+        update: object = None,
+        error_handling: bool = True,
+        **kwargs: object,
+    ) -> Promise:
         # TODO: Remove error_handling parameter once we drop the @run_async decorator
         promise = Promise(func, args, kwargs, update=update, error_handling=error_handling)
         self.__async_queue.put(promise)
@@ -357,12 +363,12 @@ class Dispatcher:
                 if self.__stop_event.is_set():
                     self.logger.debug('orderly stopping')
                     break
-                elif self.__exception_event.is_set():
+                if self.__exception_event.is_set():
                     self.logger.critical('stopping due to exception in another thread')
                     break
                 continue
 
-            self.logger.debug('Processing Update: %s' % update)
+            self.logger.debug('Processing Update: %s', update)
             self.process_update(update)
             self.update_queue.task_done()
 
@@ -387,20 +393,27 @@ class Dispatcher:
             self.__async_queue.put(None)
 
         for i, thr in enumerate(threads):
-            self.logger.debug('Waiting for async thread {}/{} to end'.format(i + 1, total))
+            self.logger.debug('Waiting for async thread %s/%s to end', i + 1, total)
             thr.join()
             self.__async_threads.remove(thr)
-            self.logger.debug('async thread {}/{} has ended'.format(i + 1, total))
+            self.logger.debug('async thread %s/%s has ended', i + 1, total)
 
     @property
     def has_running_threads(self) -> bool:
         return self.running or bool(self.__async_threads)
 
-    def process_update(self, update: Union[str, Update, TelegramError]) -> None:
-        """Processes a single update.
+    def process_update(self, update: object) -> None:
+        """Processes a single update and updates the persistence.
+
+        Note:
+            If the update is handled by least one synchronously running handlers (i.e.
+            ``run_async=False``), :meth:`update_persistence` is called *once* after all handlers
+            synchronous handlers are done. Each asynchronously running handler will trigger
+            :meth:`update_persistence` on its own.
 
         Args:
-            update (:obj:`str` | :class:`telegram.Update` | :class:`telegram.TelegramError`):
+            update (:class:`telegram.Update` | :obj:`object` | \
+                :class:`telegram.error.TelegramError`):
                 The update to process.
 
         """
@@ -414,6 +427,8 @@ class Dispatcher:
             return
 
         context = None
+        handled = False
+        sync_modes = []
 
         for group in self.groups:
             try:
@@ -422,11 +437,9 @@ class Dispatcher:
                     if check is not None and check is not False:
                         if not context and self.use_context:
                             context = CallbackContext.from_update(update, self)
+                        handled = True
+                        sync_modes.append(handler.run_async)
                         handler.handle_update(update, self, check, context)
-
-                        # If handler runs async updating immediately doesn't make sense
-                        if not handler.run_async:
-                            self.update_persistence(update=update)
                         break
 
             # Stop processing with any other handler.
@@ -436,9 +449,9 @@ class Dispatcher:
                 break
 
             # Dispatch any error.
-            except Exception as e:
+            except Exception as exc:
                 try:
-                    self.dispatch_error(update, e)
+                    self.dispatch_error(update, exc)
                 except DispatcherHandlerStop:
                     self.logger.debug('Error handler stopped further handlers')
                     break
@@ -446,6 +459,16 @@ class Dispatcher:
                 except Exception:
                     self.logger.exception('An uncaught error was raised while handling the error.')
 
+        # Update persistence, if handled
+        handled_only_async = all(sync_modes)
+        if handled:
+            # Respect default settings
+            if all(mode is DEFAULT_FALSE for mode in sync_modes) and self.bot.defaults:
+                handled_only_async = self.bot.defaults.run_async
+            # If update was only handled by async handlers, we don't need to update here
+            if not handled_only_async:
+                self.update_persistence(update=update)
+
     def add_handler(self, handler: Handler, group: int = DEFAULT_GROUP) -> None:
         """Register a handler.
 
@@ -472,17 +495,18 @@ class Dispatcher:
 
         """
         # Unfortunately due to circular imports this has to be here
-        from .conversationhandler import ConversationHandler
+        from .conversationhandler import ConversationHandler  # pylint: disable=C0415
 
         if not isinstance(handler, Handler):
-            raise TypeError('handler is not an instance of {}'.format(Handler.__name__))
+            raise TypeError(f'handler is not an instance of {Handler.__name__}')
         if not isinstance(group, int):
             raise TypeError('group is not int')
         if isinstance(handler, ConversationHandler) and handler.persistent and handler.name:
             if not self.persistence:
                 raise ValueError(
-                    "ConversationHandler {} can not be persistent if dispatcher has no "
-                    "persistence".format(handler.name))
+                    f"ConversationHandler {handler.name} can not be persistent if dispatcher has "
+                    f"no persistence"
+                )
             handler.persistence = self.persistence
             handler.conversations = self.persistence.get_conversations(handler.name)
 
@@ -507,7 +531,7 @@ class Dispatcher:
                 del self.handlers[group]
                 self.groups.remove(group)
 
-    def update_persistence(self, update: HandlerArg = None) -> None:
+    def update_persistence(self, update: object = None) -> None:
         """Update :attr:`user_data`, :attr:`chat_data` and :attr:`bot_data` in :attr:`persistence`.
 
         Args:
@@ -517,7 +541,7 @@ class Dispatcher:
         with self._update_persistence_lock:
             self.__update_persistence(update)
 
-    def __update_persistence(self, update: HandlerArg = None) -> None:
+    def __update_persistence(self, update: object = None) -> None:
         if self.persistence:
             # We use list() here in order to decouple chat_ids from self.chat_data, as dict view
             # objects will change, when the dict does and we want to loop over chat_ids
@@ -537,42 +561,50 @@ class Dispatcher:
             if self.persistence.store_bot_data:
                 try:
                     self.persistence.update_bot_data(self.bot_data)
-                except Exception as e:
+                except Exception as exc:
                     try:
-                        self.dispatch_error(update, e)
+                        self.dispatch_error(update, exc)
                     except Exception:
-                        message = 'Saving bot data raised an error and an ' \
-                                  'uncaught error was raised while handling ' \
-                                  'the error with an error_handler'
+                        message = (
+                            'Saving bot data raised an error and an '
+                            'uncaught error was raised while handling '
+                            'the error with an error_handler'
+                        )
                         self.logger.exception(message)
             if self.persistence.store_chat_data:
                 for chat_id in chat_ids:
                     try:
                         self.persistence.update_chat_data(chat_id, self.chat_data[chat_id])
-                    except Exception as e:
+                    except Exception as exc:
                         try:
-                            self.dispatch_error(update, e)
+                            self.dispatch_error(update, exc)
                         except Exception:
-                            message = 'Saving chat data raised an error and an ' \
-                                      'uncaught error was raised while handling ' \
-                                      'the error with an error_handler'
+                            message = (
+                                'Saving chat data raised an error and an '
+                                'uncaught error was raised while handling '
+                                'the error with an error_handler'
+                            )
                             self.logger.exception(message)
             if self.persistence.store_user_data:
                 for user_id in user_ids:
                     try:
                         self.persistence.update_user_data(user_id, self.user_data[user_id])
-                    except Exception as e:
+                    except Exception as exc:
                         try:
-                            self.dispatch_error(update, e)
+                            self.dispatch_error(update, exc)
                         except Exception:
-                            message = 'Saving user data raised an error and an ' \
-                                      'uncaught error was raised while handling ' \
-                                      'the error with an error_handler'
+                            message = (
+                                'Saving user data raised an error and an '
+                                'uncaught error was raised while handling '
+                                'the error with an error_handler'
+                            )
                             self.logger.exception(message)
 
-    def add_error_handler(self,
-                          callback: Callable[[Any, CallbackContext], None],
-                          run_async: bool = False) -> None:
+    def add_error_handler(
+        self,
+        callback: Callable[[object, CallbackContext], None],
+        run_async: Union[bool, DefaultValue] = DEFAULT_FALSE,  # pylint: disable=W0621
+    ) -> None:
         """Registers an error handler in the Dispatcher. This handler will receive every error
         which happens in your bot.
 
@@ -599,9 +631,14 @@ class Dispatcher:
         if callback in self.error_handlers:
             self.logger.debug('The callback is already registered as an error handler. Ignoring.')
             return
+
+        if run_async is DEFAULT_FALSE and self.bot.defaults:
+            if self.bot.defaults.run_async:
+                run_async = True
+
         self.error_handlers[callback] = run_async
 
-    def remove_error_handler(self, callback: Callable[[Any, CallbackContext], None]) -> None:
+    def remove_error_handler(self, callback: Callable[[object, CallbackContext], None]) -> None:
         """Removes an error handler.
 
         Args:
@@ -610,14 +647,13 @@ class Dispatcher:
         """
         self.error_handlers.pop(callback, None)
 
-    def dispatch_error(self,
-                       update: Optional[HandlerArg],
-                       error: Exception,
-                       promise: Promise = None) -> None:
+    def dispatch_error(
+        self, update: Optional[object], error: Exception, promise: Promise = None
+    ) -> None:
         """Dispatches an error.
 
         Args:
-            update (:obj:`str` | :class:`telegram.Update` | None): The update that caused the error
+            update (:obj:`object` | :class:`telegram.Update`): The update that caused the error.
             error (:obj:`Exception`): The error that was raised.
             promise (:class:`telegram.utils.Promise`, optional): The promise whose pooled function
                 raised the error.
@@ -627,11 +663,11 @@ class Dispatcher:
         async_kwargs = None if not promise else promise.kwargs
 
         if self.error_handlers:
-            for callback, run_async in self.error_handlers.items():
+            for callback, run_async in self.error_handlers.items():  # pylint: disable=W0621
                 if self.use_context:
-                    context = CallbackContext.from_error(update, error, self,
-                                                         async_args=async_args,
-                                                         async_kwargs=async_kwargs)
+                    context = CallbackContext.from_error(
+                        update, error, self, async_args=async_args, async_kwargs=async_kwargs
+                    )
                     if run_async:
                         self.run_async(callback, update, context, update=update)
                     else:
@@ -644,4 +680,5 @@ class Dispatcher:
 
         else:
             self.logger.exception(
-                'No error handlers are registered, logging exception.', exc_info=error)
+                'No error handlers are registered, logging exception.', exc_info=error
+            )

telegram/ext/handler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -19,32 +19,22 @@
 """This module contains the base class for handlers as used by the Dispatcher."""
 
 from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Callable, Dict, Optional, TypeVar, Union, Generic
 
-from telegram.utils.promise import Promise
-from telegram.utils.types import HandlerArg
 from telegram import Update
-from typing import Callable, TYPE_CHECKING, Any, Optional, Union, TypeVar, Dict
+from telegram.ext.utils.promise import Promise
+from telegram.utils.helpers import DefaultValue, DEFAULT_FALSE
+
 if TYPE_CHECKING:
     from telegram.ext import CallbackContext, Dispatcher
 
 RT = TypeVar('RT')
+UT = TypeVar('UT')
 
 
-class Handler(ABC):
+class Handler(Generic[UT], ABC):
     """The base class for all update handlers. Create custom handlers by inheriting from it.
 
-    Attributes:
-        callback (:obj:`callable`): The callback function for this handler.
-        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
-            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
-            the callback function.
-        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
-            the callback function.
-        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
-            the callback function.
-        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
-
     Note:
         :attr:`pass_user_data` and :attr:`pass_chat_data` determine whether a ``dict`` you
         can use to keep any data in will be sent to the :attr:`callback` function. Related to
@@ -86,15 +76,30 @@ class Handler(ABC):
         run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
             Defaults to :obj:`False`.
 
+    Attributes:
+        callback (:obj:`callable`): The callback function for this handler.
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
+            passed to the callback function.
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
+            the callback function.
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
+            the callback function.
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
+            the callback function.
+        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
+
     """
-    def __init__(self,
-                 callback: Callable[[HandlerArg, 'CallbackContext'], RT],
-                 pass_update_queue: bool = False,
-                 pass_job_queue: bool = False,
-                 pass_user_data: bool = False,
-                 pass_chat_data: bool = False,
-                 run_async: bool = False):
-        self.callback: Callable[[HandlerArg, 'CallbackContext'], RT] = callback
+
+    def __init__(
+        self,
+        callback: Callable[[UT, 'CallbackContext'], RT],
+        pass_update_queue: bool = False,
+        pass_job_queue: bool = False,
+        pass_user_data: bool = False,
+        pass_chat_data: bool = False,
+        run_async: Union[bool, DefaultValue] = DEFAULT_FALSE,
+    ):
+        self.callback = callback
         self.pass_update_queue = pass_update_queue
         self.pass_job_queue = pass_job_queue
         self.pass_user_data = pass_user_data
@@ -102,11 +107,15 @@ class Handler(ABC):
         self.run_async = run_async
 
     @abstractmethod
-    def check_update(self, update: HandlerArg) -> Optional[Union[bool, object]]:
+    def check_update(self, update: object) -> Optional[Union[bool, object]]:
         """
         This method is called to determine if an update should be handled by
         this handler instance. It should always be overridden.
 
+        Note:
+            Custom updates types can be handled by the dispatcher. Therefore, an implementation of
+            this method should always check the type of :attr:`update`.
+
         Args:
             update (:obj:`str` | :class:`telegram.Update`): The update to be tested.
 
@@ -117,11 +126,13 @@ class Handler(ABC):
 
         """
 
-    def handle_update(self,
-                      update: HandlerArg,
-                      dispatcher: 'Dispatcher',
-                      check_result: object,
-                      context: 'CallbackContext' = None) -> Union[RT, Promise]:
+    def handle_update(
+        self,
+        update: UT,
+        dispatcher: 'Dispatcher',
+        check_result: object,
+        context: 'CallbackContext' = None,
+    ) -> Union[RT, Promise]:
         """
         This method is called if it was determined that an update should indeed
         be handled by this instance. Calls :attr:`callback` along with its respectful
@@ -137,25 +148,31 @@ class Handler(ABC):
                 the dispatcher.
 
         """
+        run_async = self.run_async
+        if self.run_async is DEFAULT_FALSE and dispatcher.bot.defaults:
+            if dispatcher.bot.defaults.run_async:
+                run_async = True
+
         if context:
             self.collect_additional_context(context, update, dispatcher, check_result)
-            if self.run_async:
+            if run_async:
                 return dispatcher.run_async(self.callback, update, context, update=update)
-            else:
-                return self.callback(update, context)
-        else:
-            optional_args = self.collect_optional_args(dispatcher, update, check_result)
-            if self.run_async:
-                return dispatcher.run_async(self.callback, dispatcher.bot, update, update=update,
-                                            **optional_args)
-            else:
-                return self.callback(dispatcher.bot, update, **optional_args)  # type: ignore
+            return self.callback(update, context)
 
-    def collect_additional_context(self,
-                                   context: 'CallbackContext',
-                                   update: HandlerArg,
-                                   dispatcher: 'Dispatcher',
-                                   check_result: Any) -> None:
+        optional_args = self.collect_optional_args(dispatcher, update, check_result)
+        if run_async:
+            return dispatcher.run_async(
+                self.callback, dispatcher.bot, update, update=update, **optional_args
+            )
+        return self.callback(dispatcher.bot, update, **optional_args)  # type: ignore
+
+    def collect_additional_context(
+        self,
+        context: 'CallbackContext',
+        update: UT,
+        dispatcher: 'Dispatcher',
+        check_result: Any,
+    ) -> None:
         """Prepares additional arguments for the context. Override if needed.
 
         Args:
@@ -165,12 +182,13 @@ class Handler(ABC):
             check_result: The result (return value) from :attr:`check_update`.
 
         """
-        pass
 
-    def collect_optional_args(self,
-                              dispatcher: 'Dispatcher',
-                              update: HandlerArg = None,
-                              check_result: Any = None) -> Dict[str, Any]:
+    def collect_optional_args(
+        self,
+        dispatcher: 'Dispatcher',
+        update: UT = None,
+        check_result: Any = None,  # pylint: disable=W0613
+    ) -> Dict[str, object]:
         """
         Prepares the optional arguments. If the handler has additional optional args,
         it should subclass this method, but remember to call this super method.
@@ -184,7 +202,7 @@ class Handler(ABC):
             check_result: The result from check_update
 
         """
-        optional_args: Dict[str, Any] = dict()
+        optional_args: Dict[str, object] = dict()
 
         if self.pass_update_queue:
             optional_args['update_queue'] = dispatcher.update_queue
@@ -193,10 +211,12 @@ class Handler(ABC):
         if self.pass_user_data and isinstance(update, Update):
             user = update.effective_user
             optional_args['user_data'] = dispatcher.user_data[
-                user.id if user else None]  # type: ignore[index]
+                user.id if user else None  # type: ignore[index]
+            ]
         if self.pass_chat_data and isinstance(update, Update):
             chat = update.effective_chat
             optional_args['chat_data'] = dispatcher.chat_data[
-                chat.id if chat else None]  # type: ignore[index]
+                chat.id if chat else None  # type: ignore[index]
+            ]
 
         return optional_args

telegram/ext/inlinequeryhandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,44 +18,34 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """ This module contains the InlineQueryHandler class """
 import re
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    Dict,
+    Match,
+    Optional,
+    Pattern,
+    TypeVar,
+    Union,
+    cast,
+)
 
 from telegram import Update
+from telegram.utils.helpers import DefaultValue, DEFAULT_FALSE
 
 from .handler import Handler
 
-from telegram.utils.types import HandlerArg
-from typing import Callable, TYPE_CHECKING, Any, Optional, Union, TypeVar, Dict, Pattern, Match, \
-    cast
-
 if TYPE_CHECKING:
     from telegram.ext import CallbackContext, Dispatcher
 
 RT = TypeVar('RT')
 
 
-class InlineQueryHandler(Handler):
+class InlineQueryHandler(Handler[Update]):
     """
     Handler class to handle Telegram inline queries. Optionally based on a regex. Read the
     documentation of the ``re`` module for more information.
 
-    Attributes:
-        callback (:obj:`callable`): The callback function for this handler.
-        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
-            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
-            the callback function.
-        pattern (:obj:`str` | :obj:`Pattern`): Optional. Regex pattern to test
-            :attr:`telegram.InlineQuery.query` against.
-        pass_groups (:obj:`bool`): Determines whether ``groups`` will be passed to the
-            callback function.
-        pass_groupdict (:obj:`bool`): Determines whether ``groupdict``. will be passed to
-            the callback function.
-        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
-            the callback function.
-        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
-            the callback function.
-        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
-
     Note:
         :attr:`pass_user_data` and :attr:`pass_chat_data` determine whether a ``dict`` you
         can use to keep any data in will be sent to the :attr:`callback` function. Related to
@@ -108,25 +98,46 @@ class InlineQueryHandler(Handler):
         run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
             Defaults to :obj:`False`.
 
+    Attributes:
+        callback (:obj:`callable`): The callback function for this handler.
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
+            passed to the callback function.
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
+            the callback function.
+        pattern (:obj:`str` | :obj:`Pattern`): Optional. Regex pattern to test
+            :attr:`telegram.InlineQuery.query` against.
+        pass_groups (:obj:`bool`): Determines whether ``groups`` will be passed to the
+            callback function.
+        pass_groupdict (:obj:`bool`): Determines whether ``groupdict``. will be passed to
+            the callback function.
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
+            the callback function.
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
+            the callback function.
+        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
+
     """
 
-    def __init__(self,
-                 callback: Callable[[HandlerArg, 'CallbackContext'], RT],
-                 pass_update_queue: bool = False,
-                 pass_job_queue: bool = False,
-                 pattern: Union[str, Pattern] = None,
-                 pass_groups: bool = False,
-                 pass_groupdict: bool = False,
-                 pass_user_data: bool = False,
-                 pass_chat_data: bool = False,
-                 run_async: bool = False):
+    def __init__(
+        self,
+        callback: Callable[[Update, 'CallbackContext'], RT],
+        pass_update_queue: bool = False,
+        pass_job_queue: bool = False,
+        pattern: Union[str, Pattern] = None,
+        pass_groups: bool = False,
+        pass_groupdict: bool = False,
+        pass_user_data: bool = False,
+        pass_chat_data: bool = False,
+        run_async: Union[bool, DefaultValue] = DEFAULT_FALSE,
+    ):
         super().__init__(
             callback,
             pass_update_queue=pass_update_queue,
             pass_job_queue=pass_job_queue,
             pass_user_data=pass_user_data,
             pass_chat_data=pass_chat_data,
-            run_async=run_async)
+            run_async=run_async,
+        )
 
         if isinstance(pattern, str):
             pattern = re.compile(pattern)
@@ -135,12 +146,12 @@ class InlineQueryHandler(Handler):
         self.pass_groups = pass_groups
         self.pass_groupdict = pass_groupdict
 
-    def check_update(self, update: HandlerArg) -> Optional[Union[bool, Match]]:
+    def check_update(self, update: object) -> Optional[Union[bool, Match]]:
         """
         Determines whether an update should be passed to this handlers :attr:`callback`.
 
         Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
 
         Returns:
             :obj:`bool`
@@ -157,10 +168,12 @@ class InlineQueryHandler(Handler):
                 return True
         return None
 
-    def collect_optional_args(self,
-                              dispatcher: 'Dispatcher',
-                              update: HandlerArg = None,
-                              check_result: Optional[Union[bool, Match]] = None) -> Dict[str, Any]:
+    def collect_optional_args(
+        self,
+        dispatcher: 'Dispatcher',
+        update: Update = None,
+        check_result: Optional[Union[bool, Match]] = None,
+    ) -> Dict[str, object]:
         optional_args = super().collect_optional_args(dispatcher, update, check_result)
         if self.pattern:
             check_result = cast(Match, check_result)
@@ -170,11 +183,13 @@ class InlineQueryHandler(Handler):
                 optional_args['groupdict'] = check_result.groupdict()
         return optional_args
 
-    def collect_additional_context(self,
-                                   context: 'CallbackContext',
-                                   update: HandlerArg,
-                                   dispatcher: 'Dispatcher',
-                                   check_result: Optional[Union[bool, Match]]) -> None:
+    def collect_additional_context(
+        self,
+        context: 'CallbackContext',
+        update: Update,
+        dispatcher: 'Dispatcher',
+        check_result: Optional[Union[bool, Match]],
+    ) -> None:
         if self.pattern:
             check_result = cast(Match, check_result)
             context.matches = [check_result]

telegram/ext/jobqueue.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -16,24 +16,27 @@
 #
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
+# pylint: disable=E0401
 """This module contains the classes JobQueue and Job."""
 
 import datetime
 import logging
-import pytz
+from typing import TYPE_CHECKING, Callable, List, Optional, Tuple, Union, cast, overload
 
+import pytz
+from apscheduler.events import EVENT_JOB_ERROR, EVENT_JOB_EXECUTED, JobEvent
 from apscheduler.schedulers.background import BackgroundScheduler
-from apscheduler.triggers.cron import CronTrigger
 from apscheduler.triggers.combining import OrTrigger
-from apscheduler.events import EVENT_JOB_EXECUTED, EVENT_JOB_ERROR, JobEvent
+from apscheduler.triggers.cron import CronTrigger
+from apscheduler.job import Job as APSJob
 
 from telegram.ext.callbackcontext import CallbackContext
-
-from typing import TYPE_CHECKING, Union, Callable, Tuple, Optional, List, Any, cast, overload
 from telegram.utils.types import JSONDict
+
 if TYPE_CHECKING:
-    from telegram.ext import Dispatcher
     from telegram import Bot
+    from telegram.ext import Dispatcher
+    import apscheduler.job  # noqa: F401
 
 
 class Days:
@@ -56,8 +59,9 @@ class JobQueue:
         self._dispatcher: 'Dispatcher' = None  # type: ignore[assignment]
         self.logger = logging.getLogger(self.__class__.__name__)
         self.scheduler = BackgroundScheduler(timezone=pytz.utc)
-        self.scheduler.add_listener(self._update_persistence,
-                                    mask=EVENT_JOB_EXECUTED | EVENT_JOB_ERROR)
+        self.scheduler.add_listener(
+            self._update_persistence, mask=EVENT_JOB_EXECUTED | EVENT_JOB_ERROR
+        )
 
         # Dispatch errors and don't log them in the APS logger
         def aps_log_filter(record):  # type: ignore
@@ -74,7 +78,7 @@ class JobQueue:
     def _tz_now(self) -> datetime.datetime:
         return datetime.datetime.now(self.scheduler.timezone)
 
-    def _update_persistence(self, event: JobEvent) -> None:
+    def _update_persistence(self, event: JobEvent) -> None:  # pylint: disable=W0613
         self._dispatcher.update_persistence()
 
     def _dispatch_error(self, event: JobEvent) -> None:
@@ -82,25 +86,29 @@ class JobQueue:
             self._dispatcher.dispatch_error(None, event.exception)
         # Errors should not stop the thread.
         except Exception:
-            self.logger.exception('An error was raised while processing the job and an '
-                                  'uncaught error was raised while handling the error '
-                                  'with an error_handler.')
+            self.logger.exception(
+                'An error was raised while processing the job and an '
+                'uncaught error was raised while handling the error '
+                'with an error_handler.'
+            )
 
     @overload
     def _parse_time_input(self, time: None, shift_day: bool = False) -> None:
         ...
 
     @overload
-    def _parse_time_input(self,
-                          time: Union[float, int, datetime.timedelta, datetime.datetime,
-                                      datetime.time],
-                          shift_day: bool = False) -> datetime.datetime:
+    def _parse_time_input(
+        self,
+        time: Union[float, int, datetime.timedelta, datetime.datetime, datetime.time],
+        shift_day: bool = False,
+    ) -> datetime.datetime:
         ...
 
-    def _parse_time_input(self,
-                          time: Union[float, int, datetime.timedelta, datetime.datetime,
-                                      datetime.time, None],
-                          shift_day: bool = False) -> Optional[datetime.datetime]:
+    def _parse_time_input(
+        self,
+        time: Union[float, int, datetime.timedelta, datetime.datetime, datetime.time, None],
+        shift_day: bool = False,
+    ) -> Optional[datetime.datetime]:
         if time is None:
             return None
         if isinstance(time, (int, float)):
@@ -108,13 +116,14 @@ class JobQueue:
         if isinstance(time, datetime.timedelta):
             return self._tz_now() + time
         if isinstance(time, datetime.time):
-            dt = datetime.datetime.combine(
-                datetime.datetime.now(tz=time.tzinfo or self.scheduler.timezone).date(), time)
-            if dt.tzinfo is None:
-                dt = self.scheduler.timezone.localize(dt)
-            if shift_day and dt <= datetime.datetime.now(pytz.utc):
-                dt += datetime.timedelta(days=1)
-            return dt
+            date_time = datetime.datetime.combine(
+                datetime.datetime.now(tz=time.tzinfo or self.scheduler.timezone).date(), time
+            )
+            if date_time.tzinfo is None:
+                date_time = self.scheduler.timezone.localize(date_time)
+            if shift_day and date_time <= datetime.datetime.now(pytz.utc):
+                date_time += datetime.timedelta(days=1)
+            return date_time
         # isinstance(time, datetime.datetime):
         return time
 
@@ -131,12 +140,14 @@ class JobQueue:
             if dispatcher.bot.defaults:
                 self.scheduler.configure(timezone=dispatcher.bot.defaults.tzinfo or pytz.utc)
 
-    def run_once(self,
-                 callback: Callable[['CallbackContext'], None],
-                 when: Union[float, datetime.timedelta, datetime.datetime, datetime.time],
-                 context: object = None,
-                 name: str = None,
-                 job_kwargs: JSONDict = None) -> 'Job':
+    def run_once(
+        self,
+        callback: Callable[['CallbackContext'], None],
+        when: Union[float, datetime.timedelta, datetime.datetime, datetime.time],
+        context: object = None,
+        name: str = None,
+        job_kwargs: JSONDict = None,
+    ) -> 'Job':
         """Creates a new ``Job`` that runs once and adds it to the queue.
 
         Args:
@@ -181,29 +192,31 @@ class JobQueue:
 
         name = name or callback.__name__
         job = Job(callback, context, name, self)
-        dt = self._parse_time_input(when, shift_day=True)
+        date_time = self._parse_time_input(when, shift_day=True)
 
-        j = self.scheduler.add_job(callback,
-                                   name=name,
-                                   trigger='date',
-                                   run_date=dt,
-                                   args=self._build_args(job),
-                                   timezone=dt.tzinfo or self.scheduler.timezone,
-                                   **job_kwargs)
+        j = self.scheduler.add_job(
+            callback,
+            name=name,
+            trigger='date',
+            run_date=date_time,
+            args=self._build_args(job),
+            timezone=date_time.tzinfo or self.scheduler.timezone,
+            **job_kwargs,
+        )
 
         job.job = j
         return job
 
-    def run_repeating(self,
-                      callback: Callable[['CallbackContext'], None],
-                      interval: Union[float, datetime.timedelta],
-                      first: Union[float, datetime.timedelta, datetime.datetime,
-                                   datetime.time] = None,
-                      last: Union[float, datetime.timedelta, datetime.datetime,
-                                  datetime.time] = None,
-                      context: object = None,
-                      name: str = None,
-                      job_kwargs: JSONDict = None) -> 'Job':
+    def run_repeating(
+        self,
+        callback: Callable[['CallbackContext'], None],
+        interval: Union[float, datetime.timedelta],
+        first: Union[float, datetime.timedelta, datetime.datetime, datetime.time] = None,
+        last: Union[float, datetime.timedelta, datetime.datetime, datetime.time] = None,
+        context: object = None,
+        name: str = None,
+        job_kwargs: JSONDict = None,
+    ) -> 'Job':
         """Creates a new ``Job`` that runs at specified intervals and adds it to the queue.
 
         Args:
@@ -277,26 +290,30 @@ class JobQueue:
         if isinstance(interval, datetime.timedelta):
             interval = interval.total_seconds()
 
-        j = self.scheduler.add_job(callback,
-                                   trigger='interval',
-                                   args=self._build_args(job),
-                                   start_date=dt_first,
-                                   end_date=dt_last,
-                                   seconds=interval,
-                                   name=name,
-                                   **job_kwargs)
+        j = self.scheduler.add_job(
+            callback,
+            trigger='interval',
+            args=self._build_args(job),
+            start_date=dt_first,
+            end_date=dt_last,
+            seconds=interval,
+            name=name,
+            **job_kwargs,
+        )
 
         job.job = j
         return job
 
-    def run_monthly(self,
-                    callback: Callable[['CallbackContext'], None],
-                    when: datetime.time,
-                    day: int,
-                    context: object = None,
-                    name: str = None,
-                    day_is_strict: bool = True,
-                    job_kwargs: JSONDict = None) -> 'Job':
+    def run_monthly(
+        self,
+        callback: Callable[['CallbackContext'], None],
+        when: datetime.time,
+        day: int,
+        context: object = None,
+        name: str = None,
+        day_is_strict: bool = True,
+        job_kwargs: JSONDict = None,
+    ) -> 'Job':
         """Creates a new ``Job`` that runs on a monthly basis and adds it to the queue.
 
         Args:
@@ -332,45 +349,55 @@ class JobQueue:
         job = Job(callback, context, name, self)
 
         if day_is_strict:
-            j = self.scheduler.add_job(callback,
-                                       trigger='cron',
-                                       args=self._build_args(job),
-                                       name=name,
-                                       day=day,
-                                       hour=when.hour,
-                                       minute=when.minute,
-                                       second=when.second,
-                                       timezone=when.tzinfo or self.scheduler.timezone,
-                                       **job_kwargs)
+            j = self.scheduler.add_job(
+                callback,
+                trigger='cron',
+                args=self._build_args(job),
+                name=name,
+                day=day,
+                hour=when.hour,
+                minute=when.minute,
+                second=when.second,
+                timezone=when.tzinfo or self.scheduler.timezone,
+                **job_kwargs,
+            )
         else:
-            trigger = OrTrigger([CronTrigger(day=day,
-                                             hour=when.hour,
-                                             minute=when.minute,
-                                             second=when.second,
-                                             timezone=when.tzinfo,
-                                             **job_kwargs),
-                                 CronTrigger(day='last',
-                                             hour=when.hour,
-                                             minute=when.minute,
-                                             second=when.second,
-                                             timezone=when.tzinfo or self.scheduler.timezone,
-                                             **job_kwargs)])
-            j = self.scheduler.add_job(callback,
-                                       trigger=trigger,
-                                       args=self._build_args(job),
-                                       name=name,
-                                       **job_kwargs)
+            trigger = OrTrigger(
+                [
+                    CronTrigger(
+                        day=day,
+                        hour=when.hour,
+                        minute=when.minute,
+                        second=when.second,
+                        timezone=when.tzinfo,
+                        **job_kwargs,
+                    ),
+                    CronTrigger(
+                        day='last',
+                        hour=when.hour,
+                        minute=when.minute,
+                        second=when.second,
+                        timezone=when.tzinfo or self.scheduler.timezone,
+                        **job_kwargs,
+                    ),
+                ]
+            )
+            j = self.scheduler.add_job(
+                callback, trigger=trigger, args=self._build_args(job), name=name, **job_kwargs
+            )
 
         job.job = j
         return job
 
-    def run_daily(self,
-                  callback: Callable[['CallbackContext'], None],
-                  time: datetime.time,
-                  days: Tuple[int, ...] = Days.EVERY_DAY,
-                  context: object = None,
-                  name: str = None,
-                  job_kwargs: JSONDict = None) -> 'Job':
+    def run_daily(
+        self,
+        callback: Callable[['CallbackContext'], None],
+        time: datetime.time,
+        days: Tuple[int, ...] = Days.EVERY_DAY,
+        context: object = None,
+        name: str = None,
+        job_kwargs: JSONDict = None,
+    ) -> 'Job':
         """Creates a new ``Job`` that runs on a daily basis and adds it to the queue.
 
         Args:
@@ -384,7 +411,7 @@ class JobQueue:
             time (:obj:`datetime.time`): Time of day at which the job should run. If the timezone
                 (``time.tzinfo``) is :obj:`None`, the default timezone of the bot will be used.
             days (Tuple[:obj:`int`], optional): Defines on which days of the week the job should
-                run. Defaults to ``EVERY_DAY``
+                run (where ``0-6`` correspond to monday - sunday). Defaults to ``EVERY_DAY``
             context (:obj:`object`, optional): Additional data needed for the callback function.
                 Can be accessed through ``job.context`` in the callback. Defaults to :obj:`None`.
             name (:obj:`str`, optional): The name of the new job. Defaults to
@@ -409,25 +436,29 @@ class JobQueue:
         name = name or callback.__name__
         job = Job(callback, context, name, self)
 
-        j = self.scheduler.add_job(callback,
-                                   name=name,
-                                   args=self._build_args(job),
-                                   trigger='cron',
-                                   day_of_week=','.join([str(d) for d in days]),
-                                   hour=time.hour,
-                                   minute=time.minute,
-                                   second=time.second,
-                                   timezone=time.tzinfo or self.scheduler.timezone,
-                                   **job_kwargs)
+        j = self.scheduler.add_job(
+            callback,
+            name=name,
+            args=self._build_args(job),
+            trigger='cron',
+            day_of_week=','.join([str(d) for d in days]),
+            hour=time.hour,
+            minute=time.minute,
+            second=time.second,
+            timezone=time.tzinfo or self.scheduler.timezone,
+            **job_kwargs,
+        )
 
         job.job = j
         return job
 
-    def run_custom(self,
-                   callback: Callable[['CallbackContext'], None],
-                   job_kwargs: JSONDict,
-                   context: object = None,
-                   name: str = None) -> 'Job':
+    def run_custom(
+        self,
+        callback: Callable[['CallbackContext'], None],
+        job_kwargs: JSONDict,
+        context: object = None,
+        name: str = None,
+    ) -> 'Job':
         """Creates a new customly defined ``Job``.
 
         Args:
@@ -453,10 +484,7 @@ class JobQueue:
         name = name or callback.__name__
         job = Job(callback, context, name, self)
 
-        j = self.scheduler.add_job(callback,
-                                   args=self._build_args(job),
-                                   name=name,
-                                   **job_kwargs)
+        j = self.scheduler.add_job(callback, args=self._build_args(job), name=name, **job_kwargs)
 
         job.job = j
         return job
@@ -472,11 +500,14 @@ class JobQueue:
             self.scheduler.shutdown()
 
     def jobs(self) -> Tuple['Job', ...]:
-        """Returns a tuple of all jobs that are currently in the ``JobQueue``."""
+        """
+        Returns a tuple of all *pending/scheduled* jobs that are currently in the ``JobQueue``.
+        """
         return tuple(Job.from_aps_job(job, self) for job in self.scheduler.get_jobs())
 
     def get_jobs_by_name(self, name: str) -> Tuple['Job', ...]:
-        """Returns a tuple of jobs with the given name that are currently in the ``JobQueue``"""
+        """Returns a tuple of all *pending/scheduled* jobs with the given name that are currently
+        in the ``JobQueue``"""
         return tuple(job for job in self.jobs() if job.name == name)
 
 
@@ -493,13 +524,6 @@ class Job:
         * If :attr:`job` isn't passed on initialization, it must be set manually afterwards for
           this :class:`telegram.ext.Job` to be useful.
 
-    Attributes:
-        callback (:obj:`callable`): The callback function that should be executed by the new job.
-        context (:obj:`object`): Optional. Additional data needed for the callback function.
-        name (:obj:`str`): Optional. The name of the new job.
-        job_queue (:class:`telegram.ext.JobQueue`): Optional. The ``JobQueue`` this job belongs to.
-        job (:class:`apscheduler.job.Job`): Optional. The APS Job this job is a wrapper for.
-
     Args:
         callback (:obj:`callable`): The callback function that should be executed by the new job.
             Callback signature for context based API:
@@ -514,14 +538,23 @@ class Job:
         job_queue (:class:`telegram.ext.JobQueue`, optional): The ``JobQueue`` this job belongs to.
             Only optional for backward compatibility with ``JobQueue.put()``.
         job (:class:`apscheduler.job.Job`, optional): The APS Job this job is a wrapper for.
+
+    Attributes:
+        callback (:obj:`callable`): The callback function that should be executed by the new job.
+        context (:obj:`object`): Optional. Additional data needed for the callback function.
+        name (:obj:`str`): Optional. The name of the new job.
+        job_queue (:class:`telegram.ext.JobQueue`): Optional. The ``JobQueue`` this job belongs to.
+        job (:class:`apscheduler.job.Job`): Optional. The APS Job this job is a wrapper for.
     """
 
-    def __init__(self,
-                 callback: Callable[['CallbackContext'], None],
-                 context: object = None,
-                 name: str = None,
-                 job_queue: JobQueue = None,
-                 job: 'Job' = None):
+    def __init__(
+        self,
+        callback: Callable[['CallbackContext'], None],
+        context: object = None,
+        name: str = None,
+        job_queue: JobQueue = None,
+        job: APSJob = None,
+    ):
 
         self.callback = callback
         self.context = context
@@ -531,7 +564,7 @@ class Job:
         self._removed = False
         self._enabled = False
 
-        self.job = cast('Job', job)
+        self.job = cast(APSJob, job)
 
     def run(self, dispatcher: 'Dispatcher') -> None:
         """Executes the callback function independently of the jobs schedule."""
@@ -540,14 +573,16 @@ class Job:
                 self.callback(CallbackContext.from_job(self, dispatcher))
             else:
                 self.callback(dispatcher.bot, self)  # type: ignore[arg-type,call-arg]
-        except Exception as e:
+        except Exception as exc:
             try:
-                dispatcher.dispatch_error(None, e)
+                dispatcher.dispatch_error(None, exc)
             # Errors should not stop the thread.
             except Exception:
-                dispatcher.logger.exception('An error was raised while processing the job and an '
-                                            'uncaught error was raised while handling the error '
-                                            'with an error_handler.')
+                dispatcher.logger.exception(
+                    'An error was raised while processing the job and an '
+                    'uncaught error was raised while handling the error '
+                    'with an error_handler.'
+                )
 
     def schedule_removal(self) -> None:
         """
@@ -585,7 +620,7 @@ class Job:
         return self.job.next_run_time
 
     @classmethod
-    def from_aps_job(cls, job: 'Job', job_queue: JobQueue) -> 'Job':
+    def from_aps_job(cls, job: APSJob, job_queue: JobQueue) -> 'Job':
         # context based callbacks
         if len(job.args) == 1:
             context = job.args[0].job.context
@@ -593,7 +628,7 @@ class Job:
             context = job.args[1].context
         return cls(job.func, context=context, name=job.name, job_queue=job_queue, job=job)
 
-    def __getattr__(self, item: str) -> Any:
+    def __getattr__(self, item: str) -> object:
         return getattr(self.job, item)
 
     def __lt__(self, other: object) -> bool:

telegram/ext/messagehandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -19,44 +19,24 @@
 # TODO: Remove allow_edited
 """This module contains the MessageHandler class."""
 import warnings
-
-from telegram.utils.deprecate import TelegramDeprecationWarning
+from typing import TYPE_CHECKING, Callable, Dict, Optional, TypeVar, Union
 
 from telegram import Update
-from telegram.ext import Filters, BaseFilter
+from telegram.ext import BaseFilter, Filters
+from telegram.utils.deprecate import TelegramDeprecationWarning
+from telegram.utils.helpers import DefaultValue, DEFAULT_FALSE
+
 from .handler import Handler
 
-from telegram.utils.types import HandlerArg
-from typing import Callable, TYPE_CHECKING, Any, Optional, Union, TypeVar, Dict
 if TYPE_CHECKING:
     from telegram.ext import CallbackContext, Dispatcher
 
 RT = TypeVar('RT')
 
 
-class MessageHandler(Handler):
+class MessageHandler(Handler[Update]):
     """Handler class to handle telegram messages. They might contain text, media or status updates.
 
-    Attributes:
-        filters (:obj:`Filter`): Only allow updates with these Filters. See
-            :mod:`telegram.ext.filters` for a full list of all available filters.
-        callback (:obj:`callable`): The callback function for this handler.
-        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
-            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
-            the callback function.
-        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
-            the callback function.
-        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
-            the callback function.
-        message_updates (:obj:`bool`): Should "normal" message updates be handled?
-            Default is :obj:`None`.
-        channel_post_updates (:obj:`bool`): Should channel posts updates be handled?
-            Default is :obj:`None`.
-        edited_updates (:obj:`bool`): Should "edited" message updates be handled?
-            Default is :obj:`None`.
-        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
-
     Note:
         :attr:`pass_user_data` and :attr:`pass_chat_data` determine whether a ``dict`` you
         can use to keep any data in will be sent to the :attr:`callback` function. Related to
@@ -118,19 +98,41 @@ class MessageHandler(Handler):
     Raises:
         ValueError
 
+    Attributes:
+        filters (:obj:`Filter`): Only allow updates with these Filters. See
+            :mod:`telegram.ext.filters` for a full list of all available filters.
+        callback (:obj:`callable`): The callback function for this handler.
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
+            passed to the callback function.
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
+            the callback function.
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
+            the callback function.
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
+            the callback function.
+        message_updates (:obj:`bool`): Should "normal" message updates be handled?
+            Default is :obj:`None`.
+        channel_post_updates (:obj:`bool`): Should channel posts updates be handled?
+            Default is :obj:`None`.
+        edited_updates (:obj:`bool`): Should "edited" message updates be handled?
+            Default is :obj:`None`.
+        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
+
     """
 
-    def __init__(self,
-                 filters: BaseFilter,
-                 callback: Callable[[HandlerArg, 'CallbackContext'], RT],
-                 pass_update_queue: bool = False,
-                 pass_job_queue: bool = False,
-                 pass_user_data: bool = False,
-                 pass_chat_data: bool = False,
-                 message_updates: bool = None,
-                 channel_post_updates: bool = None,
-                 edited_updates: bool = None,
-                 run_async: bool = False):
+    def __init__(
+        self,
+        filters: BaseFilter,
+        callback: Callable[[Update, 'CallbackContext'], RT],
+        pass_update_queue: bool = False,
+        pass_job_queue: bool = False,
+        pass_user_data: bool = False,
+        pass_chat_data: bool = False,
+        message_updates: bool = None,
+        channel_post_updates: bool = None,
+        edited_updates: bool = None,
+        run_async: Union[bool, DefaultValue] = DEFAULT_FALSE,
+    ):
 
         super().__init__(
             callback,
@@ -138,42 +140,50 @@ class MessageHandler(Handler):
             pass_job_queue=pass_job_queue,
             pass_user_data=pass_user_data,
             pass_chat_data=pass_chat_data,
-            run_async=run_async)
+            run_async=run_async,
+        )
         if message_updates is False and channel_post_updates is False and edited_updates is False:
             raise ValueError(
-                'message_updates, channel_post_updates and edited_updates are all False')
+                'message_updates, channel_post_updates and edited_updates are all False'
+            )
         if filters is not None:
             self.filters = Filters.update & filters
         else:
             self.filters = Filters.update
         if message_updates is not None:
-            warnings.warn('message_updates is deprecated. See https://git.io/fxJuV for more info',
-                          TelegramDeprecationWarning,
-                          stacklevel=2)
+            warnings.warn(
+                'message_updates is deprecated. See https://git.io/fxJuV for more info',
+                TelegramDeprecationWarning,
+                stacklevel=2,
+            )
             if message_updates is False:
                 self.filters &= ~Filters.update.message
 
         if channel_post_updates is not None:
-            warnings.warn('channel_post_updates is deprecated. See https://git.io/fxJuV '
-                          'for more info',
-                          TelegramDeprecationWarning,
-                          stacklevel=2)
+            warnings.warn(
+                'channel_post_updates is deprecated. See https://git.io/fxJuV ' 'for more info',
+                TelegramDeprecationWarning,
+                stacklevel=2,
+            )
             if channel_post_updates is False:
                 self.filters &= ~Filters.update.channel_post
 
         if edited_updates is not None:
-            warnings.warn('edited_updates is deprecated. See https://git.io/fxJuV for more info',
-                          TelegramDeprecationWarning,
-                          stacklevel=2)
+            warnings.warn(
+                'edited_updates is deprecated. See https://git.io/fxJuV for more info',
+                TelegramDeprecationWarning,
+                stacklevel=2,
+            )
             if edited_updates is False:
-                self.filters &= ~(Filters.update.edited_message
-                                  | Filters.update.edited_channel_post)
+                self.filters &= ~(
+                    Filters.update.edited_message | Filters.update.edited_channel_post
+                )
 
-    def check_update(self, update: HandlerArg) -> Optional[Union[bool, Dict[str, Any]]]:
+    def check_update(self, update: object) -> Optional[Union[bool, Dict[str, object]]]:
         """Determines whether an update should be passed to this handlers :attr:`callback`.
 
         Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
 
         Returns:
             :obj:`bool`
@@ -183,10 +193,12 @@ class MessageHandler(Handler):
             return self.filters(update)
         return None
 
-    def collect_additional_context(self,
-                                   context: 'CallbackContext',
-                                   update: HandlerArg,
-                                   dispatcher: 'Dispatcher',
-                                   check_result: Optional[Union[bool, Dict[str, Any]]]) -> None:
+    def collect_additional_context(
+        self,
+        context: 'CallbackContext',
+        update: Update,
+        dispatcher: 'Dispatcher',
+        check_result: Optional[Union[bool, Dict[str, object]]],
+    ) -> None:
         if isinstance(check_result, dict):
             context.update(check_result)

telegram/ext/messagequeue.py

@@ -4,7 +4,7 @@
 # Tymofii A. Khodniev (thodnev) <thodnev@mail.ru>
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -20,14 +20,13 @@
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/]
 """A throughput-limiting message processor for Telegram bots."""
-from telegram.utils import promise
-
 import functools
-import time
-import threading
 import queue as q
+import threading
+import time
+from typing import TYPE_CHECKING, Callable, List, NoReturn
 
-from typing import Callable, Any, TYPE_CHECKING, List, NoReturn
+from telegram.ext.utils.promise import Promise
 
 if TYPE_CHECKING:
     from telegram import Bot
@@ -38,7 +37,6 @@ curtime = time.perf_counter
 
 class DelayQueueError(RuntimeError):
     """Indicates processing errors."""
-    pass
 
 
 class DelayQueue(threading.Thread):
@@ -46,14 +44,6 @@ class DelayQueue(threading.Thread):
     Processes callbacks from queue with specified throughput limits. Creates a separate thread to
     process callbacks with delays.
 
-    Attributes:
-        burst_limit (:obj:`int`): Number of maximum callbacks to process per time-window.
-        time_limit (:obj:`int`): Defines width of time-window used when each processing limit is
-            calculated.
-        exc_route (:obj:`callable`): A callable, accepting 1 positional argument; used to route
-            exceptions from processor thread to main thread;
-        name (:obj:`str`): Thread's name.
-
     Args:
         queue (:obj:`Queue`, optional): Used to pass callbacks to thread. Creates ``Queue``
             implicitly if not provided.
@@ -71,25 +61,35 @@ class DelayQueue(threading.Thread):
         name (:obj:`str`, optional): Thread's name. Defaults to ``'DelayQueue-N'``, where N is
             sequential number of object created.
 
+    Attributes:
+        burst_limit (:obj:`int`): Number of maximum callbacks to process per time-window.
+        time_limit (:obj:`int`): Defines width of time-window used when each processing limit is
+            calculated.
+        exc_route (:obj:`callable`): A callable, accepting 1 positional argument; used to route
+            exceptions from processor thread to main thread;
+        name (:obj:`str`): Thread's name.
+
     """
 
     _instcnt = 0  # instance counter
 
-    def __init__(self,
-                 queue: q.Queue = None,
-                 burst_limit: int = 30,
-                 time_limit_ms: int = 1000,
-                 exc_route: Callable[[Exception], None] = None,
-                 autostart: bool = True,
-                 name: str = None):
+    def __init__(
+        self,
+        queue: q.Queue = None,
+        burst_limit: int = 30,
+        time_limit_ms: int = 1000,
+        exc_route: Callable[[Exception], None] = None,
+        autostart: bool = True,
+        name: str = None,
+    ):
         self._queue = queue if queue is not None else q.Queue()
         self.burst_limit = burst_limit
         self.time_limit = time_limit_ms / 1000
-        self.exc_route = (exc_route if exc_route is not None else self._default_exception_handler)
+        self.exc_route = exc_route if exc_route is not None else self._default_exception_handler
         self.__exit_req = False  # flag to gently exit thread
         self.__class__._instcnt += 1
         if name is None:
-            name = '{}-{}'.format(self.__class__.__name__, self.__class__._instcnt)
+            name = f'{self.__class__.__name__}-{self.__class__._instcnt}'
         super().__init__(name=name)
         self.daemon = False
         if autostart:  # immediately start processing
@@ -153,7 +153,7 @@ class DelayQueue(threading.Thread):
 
         raise exc
 
-    def __call__(self, func: Callable, *args: Any, **kwargs: Any) -> None:
+    def __call__(self, func: Callable, *args: object, **kwargs: object) -> None:
         """Used to process callbacks in throughput-limiting thread through queue.
 
         Args:
@@ -201,24 +201,28 @@ class MessageQueue:
 
     """
 
-    def __init__(self,
-                 all_burst_limit: int = 30,
-                 all_time_limit_ms: int = 1000,
-                 group_burst_limit: int = 20,
-                 group_time_limit_ms: int = 60000,
-                 exc_route: Callable[[Exception], None] = None,
-                 autostart: bool = True):
+    def __init__(
+        self,
+        all_burst_limit: int = 30,
+        all_time_limit_ms: int = 1000,
+        group_burst_limit: int = 20,
+        group_time_limit_ms: int = 60000,
+        exc_route: Callable[[Exception], None] = None,
+        autostart: bool = True,
+    ):
         # create according delay queues, use composition
         self._all_delayq = DelayQueue(
             burst_limit=all_burst_limit,
             time_limit_ms=all_time_limit_ms,
             exc_route=exc_route,
-            autostart=autostart)
+            autostart=autostart,
+        )
         self._group_delayq = DelayQueue(
             burst_limit=group_burst_limit,
             time_limit_ms=group_time_limit_ms,
             exc_route=exc_route,
-            autostart=autostart)
+            autostart=autostart,
+        )
 
     def start(self) -> None:
         """Method is used to manually start the ``MessageQueue`` processing."""
@@ -296,12 +300,14 @@ def queuedmessage(method: Callable) -> Callable:
     """
 
     @functools.wraps(method)
-    def wrapped(self: 'Bot', *args: Any, **kwargs: Any) -> Any:
-        queued = kwargs.pop('queued',
-                            self._is_messages_queued_default)  # type: ignore[attr-defined]
+    def wrapped(self: 'Bot', *args: object, **kwargs: object) -> object:
+        # pylint: disable=W0212
+        queued = kwargs.pop(
+            'queued', self._is_messages_queued_default  # type: ignore[attr-defined]
+        )
         isgroup = kwargs.pop('isgroup', False)
         if queued:
-            prom = promise.Promise(method, (self, ) + args, kwargs)
+            prom = Promise(method, (self,) + args, kwargs)
             return self._msg_queue(prom, isgroup)  # type: ignore[attr-defined]
         return method(self, *args, **kwargs)
 

telegram/ext/picklepersistence.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -20,10 +20,9 @@
 import pickle
 from collections import defaultdict
 from copy import deepcopy
+from typing import Any, DefaultDict, Dict, Optional, Tuple
 
 from telegram.ext import BasePersistence
-
-from typing import DefaultDict, Dict, Any, Tuple, Optional
 from telegram.utils.types import ConversationDict
 
 
@@ -39,23 +38,6 @@ class PicklePersistence(BasePersistence):
         :meth:`telegram.ext.BasePersistence.replace_bot` and
         :meth:`telegram.ext.BasePersistence.insert_bot`.
 
-    Attributes:
-        filename (:obj:`str`): The filename for storing the pickle files. When :attr:`single_file`
-            is :obj:`False` this will be used as a prefix.
-        store_user_data (:obj:`bool`): Optional. Whether user_data should be saved by this
-            persistence class.
-        store_chat_data (:obj:`bool`): Optional. Whether user_data should be saved by this
-            persistence class.
-        store_bot_data (:obj:`bool`): Optional. Whether bot_data should be saved by this
-            persistence class.
-        single_file (:obj:`bool`): Optional. When :obj:`False` will store 3 separate files of
-            `filename_user_data`, `filename_chat_data` and `filename_conversations`. Default is
-            :obj:`True`.
-        on_flush (:obj:`bool`, optional): When :obj:`True` will only save to file when
-            :meth:`flush` is called and keep data in memory until that happens. When
-            :obj:`False` will store data on any transaction *and* on call to :meth:`flush`.
-            Default is :obj:`False`.
-
     Args:
         filename (:obj:`str`): The filename for storing the pickle files. When :attr:`single_file`
             is :obj:`False` this will be used as a prefix.
@@ -72,68 +54,95 @@ class PicklePersistence(BasePersistence):
             :meth:`flush` is called and keep data in memory until that happens. When
             :obj:`False` will store data on any transaction *and* on call to :meth:`flush`.
             Default is :obj:`False`.
+
+    Attributes:
+        filename (:obj:`str`): The filename for storing the pickle files. When :attr:`single_file`
+            is :obj:`False` this will be used as a prefix.
+        store_user_data (:obj:`bool`): Optional. Whether user_data should be saved by this
+            persistence class.
+        store_chat_data (:obj:`bool`): Optional. Whether user_data should be saved by this
+            persistence class.
+        store_bot_data (:obj:`bool`): Optional. Whether bot_data should be saved by this
+            persistence class.
+        single_file (:obj:`bool`): Optional. When :obj:`False` will store 3 separate files of
+            `filename_user_data`, `filename_chat_data` and `filename_conversations`. Default is
+            :obj:`True`.
+        on_flush (:obj:`bool`, optional): When :obj:`True` will only save to file when
+            :meth:`flush` is called and keep data in memory until that happens. When
+            :obj:`False` will store data on any transaction *and* on call to :meth:`flush`.
+            Default is :obj:`False`.
     """
 
-    def __init__(self,
-                 filename: str,
-                 store_user_data: bool = True,
-                 store_chat_data: bool = True,
-                 store_bot_data: bool = True,
-                 single_file: bool = True,
-                 on_flush: bool = False):
-        super().__init__(store_user_data=store_user_data,
-                         store_chat_data=store_chat_data,
-                         store_bot_data=store_bot_data)
+    def __init__(
+        self,
+        filename: str,
+        store_user_data: bool = True,
+        store_chat_data: bool = True,
+        store_bot_data: bool = True,
+        single_file: bool = True,
+        on_flush: bool = False,
+    ):
+        super().__init__(
+            store_user_data=store_user_data,
+            store_chat_data=store_chat_data,
+            store_bot_data=store_bot_data,
+        )
         self.filename = filename
         self.single_file = single_file
         self.on_flush = on_flush
         self.user_data: Optional[DefaultDict[int, Dict]] = None
         self.chat_data: Optional[DefaultDict[int, Dict]] = None
         self.bot_data: Optional[Dict] = None
-        self.conversations: Optional[Dict[str, Dict[Tuple, Any]]] = None
+        self.conversations: Optional[Dict[str, Dict[Tuple, object]]] = None
 
     def load_singlefile(self) -> None:
         try:
             filename = self.filename
-            with open(self.filename, "rb") as f:
-                data = pickle.load(f)
+            with open(self.filename, "rb") as file:
+                data = pickle.load(file)
                 self.user_data = defaultdict(dict, data['user_data'])
                 self.chat_data = defaultdict(dict, data['chat_data'])
                 # For backwards compatibility with files not containing bot data
                 self.bot_data = data.get('bot_data', {})
                 self.conversations = data['conversations']
-        except IOError:
+        except OSError:
             self.conversations = dict()
             self.user_data = defaultdict(dict)
             self.chat_data = defaultdict(dict)
             self.bot_data = {}
-        except pickle.UnpicklingError:
-            raise TypeError("File {} does not contain valid pickle data".format(filename))
-        except Exception:
-            raise TypeError("Something went wrong unpickling {}".format(filename))
+        except pickle.UnpicklingError as exc:
+            raise TypeError(f"File {filename} does not contain valid pickle data") from exc
+        except Exception as exc:
+            raise TypeError(f"Something went wrong unpickling {filename}") from exc
 
-    def load_file(self, filename: str) -> Any:
+    @staticmethod
+    def load_file(filename: str) -> Any:
         try:
-            with open(filename, "rb") as f:
-                return pickle.load(f)
-        except IOError:
+            with open(filename, "rb") as file:
+                return pickle.load(file)
+        except OSError:
             return None
-        except pickle.UnpicklingError:
-            raise TypeError("File {} does not contain valid pickle data".format(filename))
-        except Exception:
-            raise TypeError("Something went wrong unpickling {}".format(filename))
+        except pickle.UnpicklingError as exc:
+            raise TypeError(f"File {filename} does not contain valid pickle data") from exc
+        except Exception as exc:
+            raise TypeError(f"Something went wrong unpickling {filename}") from exc
 
     def dump_singlefile(self) -> None:
-        with open(self.filename, "wb") as f:
-            data = {'conversations': self.conversations, 'user_data': self.user_data,
-                    'chat_data': self.chat_data, 'bot_data': self.bot_data}
-            pickle.dump(data, f)
+        with open(self.filename, "wb") as file:
+            data = {
+                'conversations': self.conversations,
+                'user_data': self.user_data,
+                'chat_data': self.chat_data,
+                'bot_data': self.bot_data,
+            }
+            pickle.dump(data, file)
 
-    def dump_file(self, filename: str, data: Any) -> None:
-        with open(filename, "wb") as f:
-            pickle.dump(data, f)
+    @staticmethod
+    def dump_file(filename: str, data: object) -> None:
+        with open(filename, "wb") as file:
+            pickle.dump(data, file)
 
-    def get_user_data(self) -> DefaultDict[int, Dict[Any, Any]]:
+    def get_user_data(self) -> DefaultDict[int, Dict[object, object]]:
         """Returns the user_data from the pickle file if it exists or an empty :obj:`defaultdict`.
 
         Returns:
@@ -142,7 +151,7 @@ class PicklePersistence(BasePersistence):
         if self.user_data:
             pass
         elif not self.single_file:
-            filename = "{}_user_data".format(self.filename)
+            filename = f"{self.filename}_user_data"
             data = self.load_file(filename)
             if not data:
                 data = defaultdict(dict)
@@ -153,7 +162,7 @@ class PicklePersistence(BasePersistence):
             self.load_singlefile()
         return deepcopy(self.user_data)  # type: ignore[arg-type]
 
-    def get_chat_data(self) -> DefaultDict[int, Dict[Any, Any]]:
+    def get_chat_data(self) -> DefaultDict[int, Dict[object, object]]:
         """Returns the chat_data from the pickle file if it exists or an empty :obj:`defaultdict`.
 
         Returns:
@@ -162,7 +171,7 @@ class PicklePersistence(BasePersistence):
         if self.chat_data:
             pass
         elif not self.single_file:
-            filename = "{}_chat_data".format(self.filename)
+            filename = f"{self.filename}_chat_data"
             data = self.load_file(filename)
             if not data:
                 data = defaultdict(dict)
@@ -173,7 +182,7 @@ class PicklePersistence(BasePersistence):
             self.load_singlefile()
         return deepcopy(self.chat_data)  # type: ignore[arg-type]
 
-    def get_bot_data(self) -> Dict[Any, Any]:
+    def get_bot_data(self) -> Dict[object, object]:
         """Returns the bot_data from the pickle file if it exists or an empty :obj:`dict`.
 
         Returns:
@@ -182,7 +191,7 @@ class PicklePersistence(BasePersistence):
         if self.bot_data:
             pass
         elif not self.single_file:
-            filename = "{}_bot_data".format(self.filename)
+            filename = f"{self.filename}_bot_data"
             data = self.load_file(filename)
             if not data:
                 data = {}
@@ -203,7 +212,7 @@ class PicklePersistence(BasePersistence):
         if self.conversations:
             pass
         elif not self.single_file:
-            filename = "{}_conversations".format(self.filename)
+            filename = f"{self.filename}_conversations"
             data = self.load_file(filename)
             if not data:
                 data = {name: {}}
@@ -212,9 +221,9 @@ class PicklePersistence(BasePersistence):
             self.load_singlefile()
         return self.conversations.get(name, {}).copy()  # type: ignore[union-attr]
 
-    def update_conversation(self,
-                            name: str, key: Tuple[int, ...],
-                            new_state: Optional[object]) -> None:
+    def update_conversation(
+        self, name: str, key: Tuple[int, ...], new_state: Optional[object]
+    ) -> None:
         """Will update the conversations for the given handler and depending on :attr:`on_flush`
         save the pickle file.
 
@@ -230,7 +239,7 @@ class PicklePersistence(BasePersistence):
         self.conversations[name][key] = new_state
         if not self.on_flush:
             if not self.single_file:
-                filename = "{}_conversations".format(self.filename)
+                filename = f"{self.filename}_conversations"
                 self.dump_file(filename, self.conversations)
             else:
                 self.dump_singlefile()
@@ -249,7 +258,7 @@ class PicklePersistence(BasePersistence):
         self.user_data[user_id] = data
         if not self.on_flush:
             if not self.single_file:
-                filename = "{}_user_data".format(self.filename)
+                filename = f"{self.filename}_user_data"
                 self.dump_file(filename, self.user_data)
             else:
                 self.dump_singlefile()
@@ -268,7 +277,7 @@ class PicklePersistence(BasePersistence):
         self.chat_data[chat_id] = data
         if not self.on_flush:
             if not self.single_file:
-                filename = "{}_chat_data".format(self.filename)
+                filename = f"{self.filename}_chat_data"
                 self.dump_file(filename, self.chat_data)
             else:
                 self.dump_singlefile()
@@ -284,23 +293,22 @@ class PicklePersistence(BasePersistence):
         self.bot_data = data.copy()
         if not self.on_flush:
             if not self.single_file:
-                filename = "{}_bot_data".format(self.filename)
+                filename = f"{self.filename}_bot_data"
                 self.dump_file(filename, self.bot_data)
             else:
                 self.dump_singlefile()
 
     def flush(self) -> None:
-        """ Will save all data in memory to pickle file(s).
-        """
+        """Will save all data in memory to pickle file(s)."""
         if self.single_file:
             if self.user_data or self.chat_data or self.bot_data or self.conversations:
                 self.dump_singlefile()
         else:
             if self.user_data:
-                self.dump_file("{}_user_data".format(self.filename), self.user_data)
+                self.dump_file(f"{self.filename}_user_data", self.user_data)
             if self.chat_data:
-                self.dump_file("{}_chat_data".format(self.filename), self.chat_data)
+                self.dump_file(f"{self.filename}_chat_data", self.chat_data)
             if self.bot_data:
-                self.dump_file("{}_bot_data".format(self.filename), self.bot_data)
+                self.dump_file(f"{self.filename}_bot_data", self.bot_data)
             if self.conversations:
-                self.dump_file("{}_conversations".format(self.filename), self.conversations)
+                self.dump_file(f"{self.filename}_conversations", self.conversations)

telegram/ext/pollanswerhandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2019
+# Copyright (C) 2019-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -16,28 +16,17 @@
 #
 # 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 the PollAnswerHandler class."""
+
 
 from telegram import Update
+
 from .handler import Handler
 
-from telegram.utils.types import HandlerArg
 
-
-class PollAnswerHandler(Handler):
+class PollAnswerHandler(Handler[Update]):
     """Handler class to handle Telegram updates that contain a poll answer.
 
-    Attributes:
-        callback (:obj:`callable`): The callback function for this handler.
-        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
-            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
-            the callback function.
-        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
-            the callback function.
-        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
-            the callback function.
-        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
-
     Note:
         :attr:`pass_user_data` and :attr:`pass_chat_data` determine whether a ``dict`` you
         can use to keep any data in will be sent to the :attr:`callback` function. Related to
@@ -79,13 +68,25 @@ class PollAnswerHandler(Handler):
         run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
             Defaults to :obj:`False`.
 
+    Attributes:
+        callback (:obj:`callable`): The callback function for this handler.
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
+            passed to the callback function.
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
+            the callback function.
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
+            the callback function.
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
+            the callback function.
+        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
+
     """
 
-    def check_update(self, update: HandlerArg) -> bool:
+    def check_update(self, update: object) -> bool:
         """Determines whether an update should be passed to this handlers :attr:`callback`.
 
         Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
 
         Returns:
             :obj:`bool`

telegram/ext/pollhandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2019
+# Copyright (C) 2019-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -16,28 +16,17 @@
 #
 # 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 the PollHandler classes."""
+
 
 from telegram import Update
+
 from .handler import Handler
 
-from telegram.utils.types import HandlerArg
 
-
-class PollHandler(Handler):
+class PollHandler(Handler[Update]):
     """Handler class to handle Telegram updates that contain a poll.
 
-    Attributes:
-        callback (:obj:`callable`): The callback function for this handler.
-        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
-            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
-            the callback function.
-        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
-            the callback function.
-        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
-            the callback function.
-        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
-
     Note:
         :attr:`pass_user_data` and :attr:`pass_chat_data` determine whether a ``dict`` you
         can use to keep any data in will be sent to the :attr:`callback` function. Related to
@@ -79,13 +68,25 @@ class PollHandler(Handler):
         run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
             Defaults to :obj:`False`.
 
+    Attributes:
+        callback (:obj:`callable`): The callback function for this handler.
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
+            passed to the callback function.
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
+            the callback function.
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
+            the callback function.
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
+            the callback function.
+        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
+
     """
 
-    def check_update(self, update: HandlerArg) -> bool:
+    def check_update(self, update: object) -> bool:
         """Determines whether an update should be passed to this handlers :attr:`callback`.
 
         Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
 
         Returns:
             :obj:`bool`

telegram/ext/precheckoutqueryhandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,27 +18,15 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the PreCheckoutQueryHandler class."""
 
+
 from telegram import Update
+
 from .handler import Handler
 
-from telegram.utils.types import HandlerArg
 
-
-class PreCheckoutQueryHandler(Handler):
+class PreCheckoutQueryHandler(Handler[Update]):
     """Handler class to handle Telegram PreCheckout callback queries.
 
-    Attributes:
-        callback (:obj:`callable`): The callback function for this handler.
-        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
-            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
-            the callback function.
-        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
-            the callback function.
-        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
-            the callback function.
-        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
-
     Note:
         :attr:`pass_user_data` and :attr:`pass_chat_data` determine whether a ``dict`` you
         can use to keep any data in will be sent to the :attr:`callback` function. Related to
@@ -80,13 +68,25 @@ class PreCheckoutQueryHandler(Handler):
         run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
             Defaults to :obj:`False`.
 
+    Attributes:
+        callback (:obj:`callable`): The callback function for this handler.
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
+            passed to the callback function.
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
+            the callback function.
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
+            the callback function.
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
+            the callback function.
+        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
+
     """
 
-    def check_update(self, update: HandlerArg) -> bool:
+    def check_update(self, update: object) -> bool:
         """Determines whether an update should be passed to this handlers :attr:`callback`.
 
         Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
 
         Returns:
             :obj:`bool`

telegram/ext/regexhandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -20,13 +20,13 @@
 """This module contains the RegexHandler class."""
 
 import warnings
+from typing import TYPE_CHECKING, Callable, Dict, Optional, Pattern, TypeVar, Union, Any
 
+from telegram import Update
+from telegram.ext import Filters, MessageHandler
 from telegram.utils.deprecate import TelegramDeprecationWarning
+from telegram.utils.helpers import DefaultValue, DEFAULT_FALSE
 
-from telegram.ext import MessageHandler, Filters
-
-from telegram.utils.types import HandlerArg
-from typing import Callable, TYPE_CHECKING, Any, Optional, Union, TypeVar, Dict, Pattern
 if TYPE_CHECKING:
     from telegram.ext import CallbackContext, Dispatcher
 
@@ -40,23 +40,6 @@ class RegexHandler(MessageHandler):
     module for more information. The ``re.match`` function is used to determine if an update should
     be handled by this handler.
 
-    Attributes:
-        pattern (:obj:`str` | :obj:`Pattern`): The regex pattern.
-        callback (:obj:`callable`): The callback function for this handler.
-        pass_groups (:obj:`bool`): Determines whether ``groups`` will be passed to the
-            callback function.
-        pass_groupdict (:obj:`bool`): Determines whether ``groupdict``. will be passed to
-            the callback function.
-        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
-            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
-            the callback function.
-        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
-            the callback function.
-        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
-            the callback function.
-        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
-
     Note:
         This handler is being deprecated. For the same use case use:
         ``MessageHandler(Filters.regex(r'pattern'), callback)``
@@ -106,43 +89,67 @@ class RegexHandler(MessageHandler):
     Raises:
         ValueError
 
+    Attributes:
+        pattern (:obj:`str` | :obj:`Pattern`): The regex pattern.
+        callback (:obj:`callable`): The callback function for this handler.
+        pass_groups (:obj:`bool`): Determines whether ``groups`` will be passed to the
+            callback function.
+        pass_groupdict (:obj:`bool`): Determines whether ``groupdict``. will be passed to
+            the callback function.
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
+            passed to the callback function.
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
+            the callback function.
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
+            the callback function.
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
+            the callback function.
+        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
+
     """
 
-    def __init__(self,
-                 pattern: Union[str, Pattern],
-                 callback: Callable[[HandlerArg, 'CallbackContext'], RT],
-                 pass_groups: bool = False,
-                 pass_groupdict: bool = False,
-                 pass_update_queue: bool = False,
-                 pass_job_queue: bool = False,
-                 pass_user_data: bool = False,
-                 pass_chat_data: bool = False,
-                 allow_edited: bool = False,
-                 message_updates: bool = True,
-                 channel_post_updates: bool = False,
-                 edited_updates: bool = False,
-                 run_async: bool = False):
-        warnings.warn('RegexHandler is deprecated. See https://git.io/fxJuV for more info',
-                      TelegramDeprecationWarning,
-                      stacklevel=2)
-        super().__init__(Filters.regex(pattern),
-                         callback,
-                         pass_update_queue=pass_update_queue,
-                         pass_job_queue=pass_job_queue,
-                         pass_user_data=pass_user_data,
-                         pass_chat_data=pass_chat_data,
-                         message_updates=message_updates,
-                         channel_post_updates=channel_post_updates,
-                         edited_updates=edited_updates,
-                         run_async=run_async)
+    def __init__(
+        self,
+        pattern: Union[str, Pattern],
+        callback: Callable[[Update, 'CallbackContext'], RT],
+        pass_groups: bool = False,
+        pass_groupdict: bool = False,
+        pass_update_queue: bool = False,
+        pass_job_queue: bool = False,
+        pass_user_data: bool = False,
+        pass_chat_data: bool = False,
+        allow_edited: bool = False,  # pylint: disable=W0613
+        message_updates: bool = True,
+        channel_post_updates: bool = False,
+        edited_updates: bool = False,
+        run_async: Union[bool, DefaultValue] = DEFAULT_FALSE,
+    ):
+        warnings.warn(
+            'RegexHandler is deprecated. See https://git.io/fxJuV for more info',
+            TelegramDeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(
+            Filters.regex(pattern),
+            callback,
+            pass_update_queue=pass_update_queue,
+            pass_job_queue=pass_job_queue,
+            pass_user_data=pass_user_data,
+            pass_chat_data=pass_chat_data,
+            message_updates=message_updates,
+            channel_post_updates=channel_post_updates,
+            edited_updates=edited_updates,
+            run_async=run_async,
+        )
         self.pass_groups = pass_groups
         self.pass_groupdict = pass_groupdict
 
     def collect_optional_args(
-            self,
-            dispatcher: 'Dispatcher',
-            update: HandlerArg = None,
-            check_result: Optional[Union[bool, Dict[str, Any]]] = None) -> Dict[str, Any]:
+        self,
+        dispatcher: 'Dispatcher',
+        update: Update = None,
+        check_result: Optional[Union[bool, Dict[str, Any]]] = None,
+    ) -> Dict[str, object]:
         optional_args = super().collect_optional_args(dispatcher, update, check_result)
         if isinstance(check_result, dict):
             if self.pass_groups:

telegram/ext/shippingqueryhandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,27 +18,14 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the ShippingQueryHandler class."""
 
+
 from telegram import Update
 from .handler import Handler
 
-from telegram.utils.types import HandlerArg
 
-
-class ShippingQueryHandler(Handler):
+class ShippingQueryHandler(Handler[Update]):
     """Handler class to handle Telegram shipping callback queries.
 
-    Attributes:
-        callback (:obj:`callable`): The callback function for this handler.
-        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
-            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
-            the callback function.
-        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
-            the callback function.
-        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
-            the callback function.
-        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
-
     Note:
         :attr:`pass_user_data` and :attr:`pass_chat_data` determine whether a ``dict`` you
         can use to keep any data in will be sent to the :attr:`callback` function. Related to
@@ -80,13 +67,25 @@ class ShippingQueryHandler(Handler):
         run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
             Defaults to :obj:`False`.
 
+    Attributes:
+        callback (:obj:`callable`): The callback function for this handler.
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
+            passed to the callback function.
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
+            the callback function.
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
+            the callback function.
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
+            the callback function.
+        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
+
     """
 
-    def check_update(self, update: HandlerArg) -> bool:
+    def check_update(self, update: object) -> bool:
         """Determines whether an update should be passed to this handlers :attr:`callback`.
 
         Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
+            update (:class:`telegram.Update` | :obj:`object`): Incoming update.
 
         Returns:
             :obj:`bool`

telegram/ext/stringcommandhandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,17 +18,19 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the StringCommandHandler class."""
 
+from typing import TYPE_CHECKING, Callable, Dict, List, Optional, TypeVar, Union
+
+from telegram.utils.helpers import DefaultValue, DEFAULT_FALSE
+
 from .handler import Handler
 
-from telegram.utils.types import HandlerArg
-from typing import Callable, TYPE_CHECKING, Any, Optional, TypeVar, Dict, List
 if TYPE_CHECKING:
     from telegram.ext import CallbackContext, Dispatcher
 
 RT = TypeVar('RT')
 
 
-class StringCommandHandler(Handler):
+class StringCommandHandler(Handler[str]):
     """Handler class to handle string commands. Commands are string updates that start with ``/``.
 
     Note:
@@ -39,17 +41,6 @@ class StringCommandHandler(Handler):
         When setting ``run_async`` to :obj:`True`, you cannot rely on adding custom
         attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
 
-    Attributes:
-        command (:obj:`str`): The command this handler should listen for.
-        callback (:obj:`callable`): The callback function for this handler.
-        pass_args (:obj:`bool`): Determines whether the handler should be passed
-            ``args``.
-        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
-            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
-            the callback function.
-        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
-
     Args:
         command (:obj:`str`): The command this handler should listen for.
         callback (:obj:`callable`): The callback function for this handler. Will be called when
@@ -78,28 +69,42 @@ class StringCommandHandler(Handler):
         run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
             Defaults to :obj:`False`.
 
+    Attributes:
+        command (:obj:`str`): The command this handler should listen for.
+        callback (:obj:`callable`): The callback function for this handler.
+        pass_args (:obj:`bool`): Determines whether the handler should be passed
+            ``args``.
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
+            passed to the callback function.
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
+            the callback function.
+        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
+
     """
 
-    def __init__(self,
-                 command: str,
-                 callback: Callable[[HandlerArg, 'CallbackContext'], RT],
-                 pass_args: bool = False,
-                 pass_update_queue: bool = False,
-                 pass_job_queue: bool = False,
-                 run_async: bool = False):
+    def __init__(
+        self,
+        command: str,
+        callback: Callable[[str, 'CallbackContext'], RT],
+        pass_args: bool = False,
+        pass_update_queue: bool = False,
+        pass_job_queue: bool = False,
+        run_async: Union[bool, DefaultValue] = DEFAULT_FALSE,
+    ):
         super().__init__(
             callback,
             pass_update_queue=pass_update_queue,
             pass_job_queue=pass_job_queue,
-            run_async=run_async)
+            run_async=run_async,
+        )
         self.command = command
         self.pass_args = pass_args
 
-    def check_update(self, update: HandlerArg) -> Optional[List[str]]:
+    def check_update(self, update: object) -> Optional[List[str]]:
         """Determines whether an update should be passed to this handlers :attr:`callback`.
 
         Args:
-            update (:obj:`str`): An incoming command.
+            update (:obj:`object`): The incoming update.
 
         Returns:
             :obj:`bool`
@@ -111,18 +116,22 @@ class StringCommandHandler(Handler):
                 return args[1:]
         return None
 
-    def collect_optional_args(self,
-                              dispatcher: 'Dispatcher',
-                              update: HandlerArg = None,
-                              check_result: Optional[List[str]] = None) -> Dict[str, Any]:
+    def collect_optional_args(
+        self,
+        dispatcher: 'Dispatcher',
+        update: str = None,
+        check_result: Optional[List[str]] = None,
+    ) -> Dict[str, object]:
         optional_args = super().collect_optional_args(dispatcher, update, check_result)
         if self.pass_args:
             optional_args['args'] = check_result
         return optional_args
 
-    def collect_additional_context(self,
-                                   context: 'CallbackContext',
-                                   update: HandlerArg,
-                                   dispatcher: 'Dispatcher',
-                                   check_result: Optional[List[str]]) -> None:
+    def collect_additional_context(
+        self,
+        context: 'CallbackContext',
+        update: str,
+        dispatcher: 'Dispatcher',
+        check_result: Optional[List[str]],
+    ) -> None:
         context.args = check_result

telegram/ext/stringregexhandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -19,18 +19,19 @@
 """This module contains the StringRegexHandler class."""
 
 import re
+from typing import TYPE_CHECKING, Callable, Dict, Match, Optional, Pattern, TypeVar, Union
+
+from telegram.utils.helpers import DefaultValue, DEFAULT_FALSE
 
 from .handler import Handler
 
-from typing import Callable, TYPE_CHECKING, Optional, TypeVar, Match, Dict, Any, Union, Pattern
-from telegram.utils.types import HandlerArg
 if TYPE_CHECKING:
     from telegram.ext import CallbackContext, Dispatcher
 
 RT = TypeVar('RT')
 
 
-class StringRegexHandler(Handler):
+class StringRegexHandler(Handler[str]):
     """Handler class to handle string updates based on a regex which checks the update content.
 
     Read the documentation of the ``re`` module for more information. The ``re.match`` function is
@@ -44,19 +45,6 @@ class StringRegexHandler(Handler):
         When setting ``run_async`` to :obj:`True`, you cannot rely on adding custom
         attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
 
-    Attributes:
-        pattern (:obj:`str` | :obj:`Pattern`): The regex pattern.
-        callback (:obj:`callable`): The callback function for this handler.
-        pass_groups (:obj:`bool`): Determines whether ``groups`` will be passed to the
-            callback function.
-        pass_groupdict (:obj:`bool`): Determines whether ``groupdict``. will be passed to
-            the callback function.
-        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
-            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
-            the callback function.
-        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
-
     Args:
         pattern (:obj:`str` | :obj:`Pattern`): The regex pattern.
         callback (:obj:`callable`): The callback function for this handler. Will be called when
@@ -88,21 +76,37 @@ class StringRegexHandler(Handler):
         run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
             Defaults to :obj:`False`.
 
+    Attributes:
+        pattern (:obj:`str` | :obj:`Pattern`): The regex pattern.
+        callback (:obj:`callable`): The callback function for this handler.
+        pass_groups (:obj:`bool`): Determines whether ``groups`` will be passed to the
+            callback function.
+        pass_groupdict (:obj:`bool`): Determines whether ``groupdict``. will be passed to
+            the callback function.
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
+            passed to the callback function.
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
+            the callback function.
+        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
+
     """
 
-    def __init__(self,
-                 pattern: Union[str, Pattern],
-                 callback: Callable[[HandlerArg, 'CallbackContext'], RT],
-                 pass_groups: bool = False,
-                 pass_groupdict: bool = False,
-                 pass_update_queue: bool = False,
-                 pass_job_queue: bool = False,
-                 run_async: bool = False):
+    def __init__(
+        self,
+        pattern: Union[str, Pattern],
+        callback: Callable[[str, 'CallbackContext'], RT],
+        pass_groups: bool = False,
+        pass_groupdict: bool = False,
+        pass_update_queue: bool = False,
+        pass_job_queue: bool = False,
+        run_async: Union[bool, DefaultValue] = DEFAULT_FALSE,
+    ):
         super().__init__(
             callback,
             pass_update_queue=pass_update_queue,
             pass_job_queue=pass_job_queue,
-            run_async=run_async)
+            run_async=run_async,
+        )
 
         if isinstance(pattern, str):
             pattern = re.compile(pattern)
@@ -111,11 +115,11 @@ class StringRegexHandler(Handler):
         self.pass_groups = pass_groups
         self.pass_groupdict = pass_groupdict
 
-    def check_update(self, update: HandlerArg) -> Optional[Match]:
+    def check_update(self, update: object) -> Optional[Match]:
         """Determines whether an update should be passed to this handlers :attr:`callback`.
 
         Args:
-            update (:obj:`str`): An incoming command.
+            update (:obj:`object`): The incoming update.
 
         Returns:
             :obj:`bool`
@@ -127,10 +131,12 @@ class StringRegexHandler(Handler):
                 return match
         return None
 
-    def collect_optional_args(self,
-                              dispatcher: 'Dispatcher',
-                              update: HandlerArg = None,
-                              check_result: Optional[Match] = None) -> Dict[str, Any]:
+    def collect_optional_args(
+        self,
+        dispatcher: 'Dispatcher',
+        update: str = None,
+        check_result: Optional[Match] = None,
+    ) -> Dict[str, object]:
         optional_args = super().collect_optional_args(dispatcher, update, check_result)
         if self.pattern:
             if self.pass_groups and check_result:
@@ -139,10 +145,12 @@ class StringRegexHandler(Handler):
                 optional_args['groupdict'] = check_result.groupdict()
         return optional_args
 
-    def collect_additional_context(self,
-                                   context: 'CallbackContext',
-                                   update: HandlerArg,
-                                   dispatcher: 'Dispatcher',
-                                   check_result: Optional[Match]) -> None:
+    def collect_additional_context(
+        self,
+        context: 'CallbackContext',
+        update: str,
+        dispatcher: 'Dispatcher',
+        check_result: Optional[Match],
+    ) -> None:
         if self.pattern and check_result:
             context.matches = [check_result]

telegram/ext/typehandler.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,30 +18,21 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the TypeHandler class."""
 
+from typing import TYPE_CHECKING, Callable, Type, TypeVar, Union
+from telegram.utils.helpers import DefaultValue, DEFAULT_FALSE
+
 from .handler import Handler
 
-
-from typing import Callable, TYPE_CHECKING, TypeVar, Type, Any
-
 if TYPE_CHECKING:
     from telegram.ext import CallbackContext
 
 RT = TypeVar('RT')
+UT = TypeVar('UT')
 
 
-class TypeHandler(Handler):
+class TypeHandler(Handler[UT]):
     """Handler class to handle updates of custom types.
 
-    Attributes:
-        type (:obj:`type`): The ``type`` of updates this handler should process.
-        callback (:obj:`callable`): The callback function for this handler.
-        strict (:obj:`bool`): Use ``type`` instead of ``isinstance``. Default is :obj:`False`.
-        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
-            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
-            the callback function.
-        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
-
     Warning:
         When setting ``run_async`` to :obj:`True`, you cannot rely on adding custom
         attributes to :class:`telegram.ext.CallbackContext`. See its docs for more info.
@@ -72,28 +63,41 @@ class TypeHandler(Handler):
         run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
             Defaults to :obj:`False`.
 
+    Attributes:
+        type (:obj:`type`): The ``type`` of updates this handler should process.
+        callback (:obj:`callable`): The callback function for this handler.
+        strict (:obj:`bool`): Use ``type`` instead of ``isinstance``. Default is :obj:`False`.
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
+            passed to the callback function.
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
+            the callback function.
+        run_async (:obj:`bool`): Determines whether the callback will run asynchronously.
+
     """
 
-    def __init__(self,
-                 type: Type,
-                 callback: Callable[[Any, 'CallbackContext'], RT],
-                 strict: bool = False,
-                 pass_update_queue: bool = False,
-                 pass_job_queue: bool = False,
-                 run_async: bool = False):
+    def __init__(
+        self,
+        type: Type[UT],  # pylint: disable=W0622
+        callback: Callable[[UT, 'CallbackContext'], RT],
+        strict: bool = False,
+        pass_update_queue: bool = False,
+        pass_job_queue: bool = False,
+        run_async: Union[bool, DefaultValue] = DEFAULT_FALSE,
+    ):
         super().__init__(
             callback,
             pass_update_queue=pass_update_queue,
             pass_job_queue=pass_job_queue,
-            run_async=run_async)
+            run_async=run_async,
+        )
         self.type = type
         self.strict = strict
 
-    def check_update(self, update: Any) -> bool:
+    def check_update(self, update: object) -> bool:
         """Determines whether an update should be passed to this handlers :attr:`callback`.
 
         Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
+            update (:obj:`object`): Incoming update.
 
         Returns:
             :obj:`bool`
@@ -101,5 +105,4 @@ class TypeHandler(Handler):
         """
         if not self.strict:
             return isinstance(update, self.type)
-        else:
-            return type(update) is self.type
+        return type(update) is self.type  # pylint: disable=C0123

telegram/ext/updater.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -21,20 +21,19 @@
 import logging
 import ssl
 import warnings
-from threading import Thread, Lock, current_thread, Event
-from time import sleep
-from signal import signal, SIGINT, SIGTERM, SIGABRT
 from queue import Queue
+from signal import SIGABRT, SIGINT, SIGTERM, signal
+from threading import Event, Lock, Thread, current_thread
+from time import sleep
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Tuple, Union, no_type_check
 
 from telegram import Bot, TelegramError
+from telegram.error import InvalidToken, RetryAfter, TimedOut, Unauthorized
 from telegram.ext import Dispatcher, JobQueue
-from telegram.error import Unauthorized, InvalidToken, RetryAfter, TimedOut
 from telegram.utils.deprecate import TelegramDeprecationWarning
 from telegram.utils.helpers import get_signal_name
 from telegram.utils.request import Request
-from telegram.utils.webhookhandler import (WebhookServer, WebhookAppClass)
-
-from typing import Callable, Dict, TYPE_CHECKING, Any, List, Union, Tuple, no_type_check, Optional
+from telegram.ext.utils.webhookhandler import WebhookAppClass, WebhookServer
 
 if TYPE_CHECKING:
     from telegram.ext import BasePersistence, Defaults
@@ -51,19 +50,10 @@ class Updater:
     production, use a webhook to receive updates. This is achieved using the WebhookServer and
     WebhookHandler classes.
 
-
-    Attributes:
-        bot (:class:`telegram.Bot`): The bot used with this Updater.
-        user_sig_handler (:obj:`function`): Optional. Function to be called when a signal is
-            received.
-        update_queue (:obj:`Queue`): Queue for the updates.
-        job_queue (:class:`telegram.ext.JobQueue`): Jobqueue for the updater.
-        dispatcher (:class:`telegram.ext.Dispatcher`): Dispatcher that handles the updates and
-            dispatches them to the handlers.
-        running (:obj:`bool`): Indicates if the updater is running.
-        persistence (:class:`telegram.ext.BasePersistence`): Optional. The persistence class to
-            store data that should be persistent over restarts.
-        use_context (:obj:`bool`): Optional. :obj:`True` if using context based callbacks.
+    Note:
+        * You must supply either a :attr:`bot` or a :attr:`token` argument.
+        * If you supply a :attr:`bot`, you will need to pass :attr:`defaults` to *both* the bot and
+          the :class:`telegram.ext.Updater`.
 
     Args:
         token (:obj:`str`, optional): The bot's token given by the @BotFather.
@@ -96,38 +86,51 @@ class Updater:
         defaults (:class:`telegram.ext.Defaults`, optional): An object containing default values to
             be used if not set explicitly in the bot methods.
 
-    Note:
-        * You must supply either a :attr:`bot` or a :attr:`token` argument.
-        * If you supply a :attr:`bot`, you will need to pass :attr:`defaults` to *both* the bot and
-          the :class:`telegram.ext.Updater`.
-
     Raises:
         ValueError: If both :attr:`token` and :attr:`bot` are passed or none of them.
 
+
+    Attributes:
+        bot (:class:`telegram.Bot`): The bot used with this Updater.
+        user_sig_handler (:obj:`function`): Optional. Function to be called when a signal is
+            received.
+        update_queue (:obj:`Queue`): Queue for the updates.
+        job_queue (:class:`telegram.ext.JobQueue`): Jobqueue for the updater.
+        dispatcher (:class:`telegram.ext.Dispatcher`): Dispatcher that handles the updates and
+            dispatches them to the handlers.
+        running (:obj:`bool`): Indicates if the updater is running.
+        persistence (:class:`telegram.ext.BasePersistence`): Optional. The persistence class to
+            store data that should be persistent over restarts.
+        use_context (:obj:`bool`): Optional. :obj:`True` if using context based callbacks.
+
     """
 
     _request = None
 
-    def __init__(self,
-                 token: str = None,
-                 base_url: str = None,
-                 workers: int = 4,
-                 bot: Bot = None,
-                 private_key: bytes = None,
-                 private_key_password: bytes = None,
-                 user_sig_handler: Callable = None,
-                 request_kwargs: Dict[str, Any] = None,
-                 persistence: 'BasePersistence' = None,
-                 defaults: 'Defaults' = None,
-                 use_context: bool = True,
-                 dispatcher: Dispatcher = None,
-                 base_file_url: str = None):
+    def __init__(
+        self,
+        token: str = None,
+        base_url: str = None,
+        workers: int = 4,
+        bot: Bot = None,
+        private_key: bytes = None,
+        private_key_password: bytes = None,
+        user_sig_handler: Callable = None,
+        request_kwargs: Dict[str, Any] = None,
+        persistence: 'BasePersistence' = None,
+        defaults: 'Defaults' = None,
+        use_context: bool = True,
+        dispatcher: Dispatcher = None,
+        base_file_url: str = None,
+    ):
 
         if defaults and bot:
-            warnings.warn('Passing defaults to an Updater has no effect when a Bot is passed '
-                          'as well. Pass them to the Bot instead.',
-                          TelegramDeprecationWarning,
-                          stacklevel=2)
+            warnings.warn(
+                'Passing defaults to an Updater has no effect when a Bot is passed '
+                'as well. Pass them to the Bot instead.',
+                TelegramDeprecationWarning,
+                stacklevel=2,
+            )
 
         if dispatcher is None:
             if (token is None) and (bot is None):
@@ -156,7 +159,8 @@ class Updater:
                 if bot.request.con_pool_size < con_pool_size:
                     self.logger.warning(
                         'Connection pool of Request object is smaller than optimal value (%s)',
-                        con_pool_size)
+                        con_pool_size,
+                    )
             else:
                 # we need a connection pool the size of:
                 # * for each of the workers
@@ -169,24 +173,28 @@ class Updater:
                 if 'con_pool_size' not in request_kwargs:
                     request_kwargs['con_pool_size'] = con_pool_size
                 self._request = Request(**request_kwargs)
-                self.bot = Bot(token,  # type: ignore[arg-type]
-                               base_url,
-                               base_file_url=base_file_url,
-                               request=self._request,
-                               private_key=private_key,
-                               private_key_password=private_key_password,
-                               defaults=defaults)
+                self.bot = Bot(
+                    token,  # type: ignore[arg-type]
+                    base_url,
+                    base_file_url=base_file_url,
+                    request=self._request,
+                    private_key=private_key,
+                    private_key_password=private_key_password,
+                    defaults=defaults,
+                )
             self.update_queue: Queue = Queue()
             self.job_queue = JobQueue()
             self.__exception_event = Event()
             self.persistence = persistence
-            self.dispatcher = Dispatcher(self.bot,
-                                         self.update_queue,
-                                         job_queue=self.job_queue,
-                                         workers=workers,
-                                         exception_event=self.__exception_event,
-                                         persistence=persistence,
-                                         use_context=use_context)
+            self.dispatcher = Dispatcher(
+                self.bot,
+                self.update_queue,
+                job_queue=self.job_queue,
+                workers=workers,
+                exception_event=self.__exception_event,
+                persistence=persistence,
+                use_context=use_context,
+            )
             self.job_queue.set_dispatcher(self.dispatcher)
         else:
             con_pool_size = dispatcher.workers + 4
@@ -195,7 +203,8 @@ class Updater:
             if self.bot.request.con_pool_size < con_pool_size:
                 self.logger.warning(
                     'Connection pool of Request object is smaller than optimal value (%s)',
-                    con_pool_size)
+                    con_pool_size,
+                )
             self.update_queue = dispatcher.update_queue
             self.__exception_event = dispatcher.exception_event
             self.persistence = dispatcher.persistence
@@ -210,32 +219,36 @@ class Updater:
         self.__lock = Lock()
         self.__threads: List[Thread] = []
 
-    def _init_thread(self, target: Callable, name: str, *args: Any, **kwargs: Any) -> None:
-        thr = Thread(target=self._thread_wrapper,
-                     name="Bot:{}:{}".format(self.bot.id, name),
-                     args=(target,) + args,
-                     kwargs=kwargs)
+    def _init_thread(self, target: Callable, name: str, *args: object, **kwargs: object) -> None:
+        thr = Thread(
+            target=self._thread_wrapper,
+            name=f"Bot:{self.bot.id}:{name}",
+            args=(target,) + args,
+            kwargs=kwargs,
+        )
         thr.start()
         self.__threads.append(thr)
 
-    def _thread_wrapper(self, target: Callable, *args: Any, **kwargs: Any) -> None:
+    def _thread_wrapper(self, target: Callable, *args: object, **kwargs: object) -> None:
         thr_name = current_thread().name
-        self.logger.debug('{} - started'.format(thr_name))
+        self.logger.debug('%s - started', thr_name)
         try:
             target(*args, **kwargs)
         except Exception:
             self.__exception_event.set()
             self.logger.exception('unhandled exception in %s', thr_name)
             raise
-        self.logger.debug('{} - ended'.format(thr_name))
+        self.logger.debug('%s - ended', thr_name)
 
-    def start_polling(self,
-                      poll_interval: float = 0.0,
-                      timeout: float = 10,
-                      clean: bool = False,
-                      bootstrap_retries: int = -1,
-                      read_latency: float = 2.,
-                      allowed_updates: List[str] = None) -> Optional[Queue]:
+    def start_polling(
+        self,
+        poll_interval: float = 0.0,
+        timeout: float = 10,
+        clean: bool = False,
+        bootstrap_retries: int = -1,
+        read_latency: float = 2.0,
+        allowed_updates: List[str] = None,
+    ) -> Optional[Queue]:
         """Starts polling updates from Telegram.
 
         Args:
@@ -270,9 +283,17 @@ class Updater:
                 dispatcher_ready = Event()
                 polling_ready = Event()
                 self._init_thread(self.dispatcher.start, "dispatcher", ready=dispatcher_ready)
-                self._init_thread(self._start_polling, "updater", poll_interval, timeout,
-                                  read_latency, bootstrap_retries, clean, allowed_updates,
-                                  ready=polling_ready)
+                self._init_thread(
+                    self._start_polling,
+                    "updater",
+                    poll_interval,
+                    timeout,
+                    read_latency,
+                    bootstrap_retries,
+                    clean,
+                    allowed_updates,
+                    ready=polling_ready,
+                )
 
                 self.logger.debug('Waiting for Dispatcher and polling to start')
                 dispatcher_ready.wait()
@@ -282,17 +303,19 @@ class Updater:
                 return self.update_queue
             return None
 
-    def start_webhook(self,
-                      listen: str = '127.0.0.1',
-                      port: int = 80,
-                      url_path: str = '',
-                      cert: str = None,
-                      key: str = None,
-                      clean: bool = False,
-                      bootstrap_retries: int = 0,
-                      webhook_url: str = None,
-                      allowed_updates: List[str] = None,
-                      force_event_loop: bool = False) -> Optional[Queue]:
+    def start_webhook(
+        self,
+        listen: str = '127.0.0.1',
+        port: int = 80,
+        url_path: str = '',
+        cert: str = None,
+        key: str = None,
+        clean: bool = False,
+        bootstrap_retries: int = 0,
+        webhook_url: str = None,
+        allowed_updates: List[str] = None,
+        force_event_loop: bool = False,
+    ) -> Optional[Queue]:
         """
         Starts a small http server to listen for updates via webhook. If cert
         and key are not provided, the webhook will be started directly on
@@ -344,9 +367,21 @@ class Updater:
                 dispatcher_ready = Event()
                 self.job_queue.start()
                 self._init_thread(self.dispatcher.start, "dispatcher", dispatcher_ready)
-                self._init_thread(self._start_webhook, "updater", listen, port, url_path, cert,
-                                  key, bootstrap_retries, clean, webhook_url, allowed_updates,
-                                  ready=webhook_ready, force_event_loop=force_event_loop)
+                self._init_thread(
+                    self._start_webhook,
+                    "updater",
+                    listen,
+                    port,
+                    url_path,
+                    cert,
+                    key,
+                    bootstrap_retries,
+                    clean,
+                    webhook_url,
+                    allowed_updates,
+                    ready=webhook_ready,
+                    force_event_loop=force_event_loop,
+                )
 
                 self.logger.debug('Waiting for Dispatcher and Webhook to start')
                 webhook_ready.wait()
@@ -357,8 +392,16 @@ class Updater:
             return None
 
     @no_type_check
-    def _start_polling(self, poll_interval, timeout, read_latency, bootstrap_retries, clean,
-                       allowed_updates, ready=None):  # pragma: no cover
+    def _start_polling(
+        self,
+        poll_interval,
+        timeout,
+        read_latency,
+        bootstrap_retries,
+        clean,
+        allowed_updates,
+        ready=None,
+    ):  # pragma: no cover
         # Thread target of thread 'updater'. Runs in background, pulls
         # updates from Telegram and inserts them in the update queue of the
         # Dispatcher.
@@ -370,10 +413,12 @@ class Updater:
         self.logger.debug('Bootstrap done')
 
         def polling_action_cb():
-            updates = self.bot.get_updates(self.last_update_id,
-                                           timeout=timeout,
-                                           read_latency=read_latency,
-                                           allowed_updates=allowed_updates)
+            updates = self.bot.get_updates(
+                self.last_update_id,
+                timeout=timeout,
+                read_latency=read_latency,
+                allowed_updates=allowed_updates,
+            )
 
             if updates:
                 if not self.running:
@@ -393,8 +438,9 @@ class Updater:
         if ready is not None:
             ready.set()
 
-        self._network_loop_retry(polling_action_cb, polling_onerr_cb, 'getting Updates',
-                                 poll_interval)
+        self._network_loop_retry(
+            polling_action_cb, polling_onerr_cb, 'getting Updates', poll_interval
+        )
 
     @no_type_check
     def _network_loop_retry(self, action_cb, onerr_cb, description, interval):
@@ -418,9 +464,9 @@ class Updater:
             try:
                 if not action_cb():
                     break
-            except RetryAfter as e:
-                self.logger.info('%s', e)
-                cur_interval = 0.5 + e.retry_after
+            except RetryAfter as exc:
+                self.logger.info('%s', exc)
+                cur_interval = 0.5 + exc.retry_after
             except TimedOut as toe:
                 self.logger.debug('Timed out %s: %s', description, toe)
                 # If failure is due to timeout, we should retry asap.
@@ -428,9 +474,9 @@ class Updater:
             except InvalidToken as pex:
                 self.logger.error('Invalid token; aborting')
                 raise pex
-            except TelegramError as te:
-                self.logger.error('Error while %s: %s', description, te)
-                onerr_cb(te)
+            except TelegramError as telegram_exc:
+                self.logger.error('Error while %s: %s', description, telegram_exc)
+                onerr_cb(telegram_exc)
                 cur_interval = self._increase_poll_interval(cur_interval)
             else:
                 cur_interval = interval
@@ -450,12 +496,24 @@ class Updater:
         return current_interval
 
     @no_type_check
-    def _start_webhook(self, listen, port, url_path, cert, key, bootstrap_retries, clean,
-                       webhook_url, allowed_updates, ready=None, force_event_loop=False):
+    def _start_webhook(
+        self,
+        listen,
+        port,
+        url_path,
+        cert,
+        key,
+        bootstrap_retries,
+        clean,
+        webhook_url,
+        allowed_updates,
+        ready=None,
+        force_event_loop=False,
+    ):
         self.logger.debug('Updater thread started (webhook)')
         use_ssl = cert is not None and key is not None
         if not url_path.startswith('/'):
-            url_path = '/{}'.format(url_path)
+            url_path = f'/{url_path}'
 
         # Create Tornado app instance
         app = WebhookAppClass(url_path, self.bot, self.update_queue)
@@ -466,8 +524,8 @@ class Updater:
             try:
                 ssl_ctx = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
                 ssl_ctx.load_cert_chain(cert, key)
-            except ssl.SSLError:
-                raise TelegramError('Invalid SSL Certificate')
+            except ssl.SSLError as exc:
+                raise TelegramError('Invalid SSL Certificate') from exc
         else:
             ssl_ctx = None
 
@@ -479,29 +537,29 @@ class Updater:
             if not webhook_url:
                 webhook_url = self._gen_webhook_url(listen, port, url_path)
 
-            self._bootstrap(max_retries=bootstrap_retries,
-                            clean=clean,
-                            webhook_url=webhook_url,
-                            cert=open(cert, 'rb'),
-                            allowed_updates=allowed_updates)
+            self._bootstrap(
+                max_retries=bootstrap_retries,
+                clean=clean,
+                webhook_url=webhook_url,
+                cert=open(cert, 'rb'),
+                allowed_updates=allowed_updates,
+            )
         elif clean:
-            self.logger.warning("cleaning updates is not supported if "
-                                "SSL-termination happens elsewhere; skipping")
+            self.logger.warning(
+                "cleaning updates is not supported if "
+                "SSL-termination happens elsewhere; skipping"
+            )
 
         self.httpd.serve_forever(force_event_loop=force_event_loop, ready=ready)
 
     @staticmethod
     def _gen_webhook_url(listen: str, port: int, url_path: str) -> str:
-        return 'https://{listen}:{port}{path}'.format(listen=listen, port=port, path=url_path)
+        return f'https://{listen}:{port}{url_path}'
 
     @no_type_check
-    def _bootstrap(self,
-                   max_retries,
-                   clean,
-                   webhook_url,
-                   allowed_updates,
-                   cert=None,
-                   bootstrap_interval=5):
+    def _bootstrap(
+        self, max_retries, clean, webhook_url, allowed_updates, cert=None, bootstrap_interval=5
+    ):
         retries = [0]
 
         def bootstrap_del_webhook():
@@ -516,16 +574,17 @@ class Updater:
             return False
 
         def bootstrap_set_webhook():
-            self.bot.set_webhook(url=webhook_url,
-                                 certificate=cert,
-                                 allowed_updates=allowed_updates)
+            self.bot.set_webhook(
+                url=webhook_url, certificate=cert, allowed_updates=allowed_updates
+            )
             return False
 
         def bootstrap_onerr_cb(exc):
             if not isinstance(exc, Unauthorized) and (max_retries < 0 or retries[0] < max_retries):
                 retries[0] += 1
-                self.logger.warning('Failed bootstrap phase; try=%s max_retries=%s', retries[0],
-                                    max_retries)
+                self.logger.warning(
+                    'Failed bootstrap phase; try=%s max_retries=%s', retries[0], max_retries
+                )
             else:
                 self.logger.error('Failed bootstrap phase after %s retries (%s)', retries[0], exc)
                 raise exc
@@ -535,22 +594,34 @@ class Updater:
         # We also take this chance to delete pre-configured webhook if this is a polling Updater.
         # NOTE: We don't know ahead if a webhook is configured, so we just delete.
         if clean or not webhook_url:
-            self._network_loop_retry(bootstrap_del_webhook, bootstrap_onerr_cb,
-                                     'bootstrap del webhook', bootstrap_interval)
+            self._network_loop_retry(
+                bootstrap_del_webhook,
+                bootstrap_onerr_cb,
+                'bootstrap del webhook',
+                bootstrap_interval,
+            )
             retries[0] = 0
 
         # Clean pending messages, if requested.
         if clean:
-            self._network_loop_retry(bootstrap_clean_updates, bootstrap_onerr_cb,
-                                     'bootstrap clean updates', bootstrap_interval)
+            self._network_loop_retry(
+                bootstrap_clean_updates,
+                bootstrap_onerr_cb,
+                'bootstrap clean updates',
+                bootstrap_interval,
+            )
             retries[0] = 0
             sleep(1)
 
         # Restore/set webhook settings, if needed. Again, we don't know ahead if a webhook is set,
         # so we set it anyhow.
         if webhook_url:
-            self._network_loop_retry(bootstrap_set_webhook, bootstrap_onerr_cb,
-                                     'bootstrap set webhook', bootstrap_interval)
+            self._network_loop_retry(
+                bootstrap_set_webhook,
+                bootstrap_onerr_cb,
+                'bootstrap set webhook',
+                bootstrap_interval,
+            )
 
     def stop(self) -> None:
         """Stops the polling/webhook thread, the dispatcher and the job queue."""
@@ -573,9 +644,11 @@ class Updater:
     @no_type_check
     def _stop_httpd(self) -> None:
         if self.httpd:
-            self.logger.debug('Waiting for current webhook connection to be '
-                              'closed... Send a Telegram message to the bot to exit '
-                              'immediately.')
+            self.logger.debug(
+                'Waiting for current webhook connection to be '
+                'closed... Send a Telegram message to the bot to exit '
+                'immediately.'
+            )
             self.httpd.shutdown()
             self.httpd = None
 
@@ -587,17 +660,18 @@ class Updater:
     @no_type_check
     def _join_threads(self) -> None:
         for thr in self.__threads:
-            self.logger.debug('Waiting for {} thread to end'.format(thr.name))
+            self.logger.debug('Waiting for %s thread to end', thr.name)
             thr.join()
-            self.logger.debug('{} thread has ended'.format(thr.name))
+            self.logger.debug('%s thread has ended', thr.name)
         self.__threads = []
 
     @no_type_check
     def signal_handler(self, signum, frame) -> None:
         self.is_idle = False
         if self.running:
-            self.logger.info('Received signal {} ({}), stopping...'.format(
-                signum, get_signal_name(signum)))
+            self.logger.info(
+                'Received signal %s (%s), stopping...', signum, get_signal_name(signum)
+            )
             if self.persistence:
                 # Update user_data, chat_data and bot_data before flushing
                 self.dispatcher.update_persistence()
@@ -607,7 +681,9 @@ class Updater:
                 self.user_sig_handler(signum, frame)
         else:
             self.logger.warning('Exiting immediately!')
+            # pylint: disable=C0415,W0212
             import os
+
             os._exit(1)
 
     def idle(self, stop_signals: Union[List, Tuple] = (SIGINT, SIGTERM, SIGABRT)) -> None:

telegram/ext/utils/__init__.py

@@ -0,0 +1,17 @@
+#
+#  A library that provides a Python interface to the Telegram Bot API
+#  Copyright (C) 2015-2021
+#  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/].

telegram/ext/utils/promise.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2021
+# 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 the Promise class."""
+
+import logging
+from threading import Event
+from typing import Callable, List, Optional, Tuple, TypeVar, Union
+
+from telegram.utils.types import JSONDict
+
+RT = TypeVar('RT')
+
+
+logger = logging.getLogger(__name__)
+
+
+class Promise:
+    """A simple Promise implementation for use with the run_async decorator, DelayQueue etc.
+
+    Args:
+        pooled_function (:obj:`callable`): The callable that will be called concurrently.
+        args (:obj:`list` | :obj:`tuple`): Positional arguments for :attr:`pooled_function`.
+        kwargs (:obj:`dict`): Keyword arguments for :attr:`pooled_function`.
+        update (:class:`telegram.Update` | :obj:`object`, optional): The update this promise is
+            associated with.
+        error_handling (:obj:`bool`, optional): Whether exceptions raised by :attr:`func`
+            may be handled by error handlers. Defaults to :obj:`True`.
+
+    Attributes:
+        pooled_function (:obj:`callable`): The callable that will be called concurrently.
+        args (:obj:`list` | :obj:`tuple`): Positional arguments for :attr:`pooled_function`.
+        kwargs (:obj:`dict`): Keyword arguments for :attr:`pooled_function`.
+        done (:obj:`threading.Event`): Is set when the result is available.
+        update (:class:`telegram.Update` | :obj:`object`): Optional. The update this promise is
+            associated with.
+        error_handling (:obj:`bool`): Optional. Whether exceptions raised by :attr:`func`
+            may be handled by error handlers. Defaults to :obj:`True`.
+
+    """
+
+    # TODO: Remove error_handling parameter once we drop the @run_async decorator
+    def __init__(
+        self,
+        pooled_function: Callable[..., RT],
+        args: Union[List, Tuple],
+        kwargs: JSONDict,
+        update: object = None,
+        error_handling: bool = True,
+    ):
+        self.pooled_function = pooled_function
+        self.args = args
+        self.kwargs = kwargs
+        self.update = update
+        self.error_handling = error_handling
+        self.done = Event()
+        self._result: Optional[RT] = None
+        self._exception: Optional[Exception] = None
+
+    def run(self) -> None:
+        """Calls the :attr:`pooled_function` callable."""
+
+        try:
+            self._result = self.pooled_function(*self.args, **self.kwargs)
+
+        except Exception as exc:
+            self._exception = exc
+
+        finally:
+            self.done.set()
+
+    def __call__(self) -> None:
+        self.run()
+
+    def result(self, timeout: float = None) -> Optional[RT]:
+        """Return the result of the ``Promise``.
+
+        Args:
+            timeout (:obj:`float`, optional): Maximum time in seconds to wait for the result to be
+                calculated. ``None`` means indefinite. Default is ``None``.
+
+        Returns:
+            Returns the return value of :attr:`pooled_function` or ``None`` if the ``timeout``
+            expires.
+
+        Raises:
+            object exception raised by :attr:`pooled_function`.
+        """
+        self.done.wait(timeout=timeout)
+        if self._exception is not None:
+            raise self._exception  # pylint: disable=raising-bad-type
+        return self._result
+
+    @property
+    def exception(self) -> Optional[Exception]:
+        """The exception raised by :attr:`pooled_function` or ``None`` if no exception has been
+        raised (yet)."""
+        return self._exception

telegram/ext/utils/webhookhandler.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2021
+# 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/].
+# pylint: disable=E0401, C0114
+
+import asyncio
+import logging
+import os
+import sys
+from queue import Queue
+from ssl import SSLContext
+from threading import Event, Lock
+from typing import TYPE_CHECKING, Any, Optional
+
+import tornado.web
+from tornado import httputil
+from tornado.httpserver import HTTPServer
+from tornado.ioloop import IOLoop
+
+from telegram import Update
+from telegram.utils.types import JSONDict
+
+if TYPE_CHECKING:
+    from telegram import Bot
+
+try:
+    import ujson as json
+except ImportError:
+    import json  # type: ignore[no-redef]
+
+
+class WebhookServer:
+    def __init__(
+        self, listen: str, port: int, webhook_app: 'WebhookAppClass', ssl_ctx: SSLContext
+    ):
+        self.http_server = HTTPServer(webhook_app, ssl_options=ssl_ctx)
+        self.listen = listen
+        self.port = port
+        self.loop: Optional[IOLoop] = None
+        self.logger = logging.getLogger(__name__)
+        self.is_running = False
+        self.server_lock = Lock()
+        self.shutdown_lock = Lock()
+
+    def serve_forever(self, force_event_loop: bool = False, ready: Event = None) -> None:
+        with self.server_lock:
+            self.is_running = True
+            self.logger.debug('Webhook Server started.')
+            self._ensure_event_loop(force_event_loop=force_event_loop)
+            self.loop = IOLoop.current()
+            self.http_server.listen(self.port, address=self.listen)
+
+            if ready is not None:
+                ready.set()
+
+            self.loop.start()
+            self.logger.debug('Webhook Server stopped.')
+            self.is_running = False
+
+    def shutdown(self) -> None:
+        with self.shutdown_lock:
+            if not self.is_running:
+                self.logger.warning('Webhook Server already stopped.')
+                return
+            self.loop.add_callback(self.loop.stop)  # type: ignore
+
+    def handle_error(self, request: object, client_address: str) -> None:  # pylint: disable=W0613
+        """Handle an error gracefully."""
+        self.logger.debug(
+            'Exception happened during processing of request from %s',
+            client_address,
+            exc_info=True,
+        )
+
+    def _ensure_event_loop(self, force_event_loop: bool = False) -> None:
+        """If there's no asyncio event loop set for the current thread - create one."""
+        try:
+            loop = asyncio.get_event_loop()
+            if (
+                not force_event_loop
+                and os.name == 'nt'
+                and sys.version_info >= (3, 8)
+                and isinstance(loop, asyncio.ProactorEventLoop)
+            ):
+                raise TypeError(
+                    '`ProactorEventLoop` is incompatible with '
+                    'Tornado. Please switch to `SelectorEventLoop`.'
+                )
+        except RuntimeError:
+            # Python 3.8 changed default asyncio event loop implementation on windows
+            # from SelectorEventLoop to ProactorEventLoop. At the time of this writing
+            # Tornado doesn't support ProactorEventLoop and suggests that end users
+            # change asyncio event loop policy to WindowsSelectorEventLoopPolicy.
+            # https://github.com/tornadoweb/tornado/issues/2608
+            # To avoid changing the global event loop policy, we manually construct
+            # a SelectorEventLoop instance instead of using asyncio.new_event_loop().
+            # Note that the fix is not applied in the main thread, as that can break
+            # user code in even more ways than changing the global event loop policy can,
+            # and because Updater always starts its webhook server in a separate thread.
+            # Ideally, we would want to check that Tornado actually raises the expected
+            # NotImplementedError, but it's not possible to cleanly recover from that
+            # exception in current Tornado version.
+            if (
+                os.name == 'nt'
+                and sys.version_info >= (3, 8)
+                # OS+version check makes hasattr check redundant, but just to be sure
+                and hasattr(asyncio, 'WindowsProactorEventLoopPolicy')
+                and (
+                    isinstance(
+                        asyncio.get_event_loop_policy(),
+                        asyncio.WindowsProactorEventLoopPolicy,  # pylint: disable=E1101
+                    )
+                )
+            ):  # pylint: disable=E1101
+                self.logger.debug(
+                    'Applying Tornado asyncio event loop fix for Python 3.8+ on Windows'
+                )
+                loop = asyncio.SelectorEventLoop()
+            else:
+                loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+
+
+class WebhookAppClass(tornado.web.Application):
+    def __init__(self, webhook_path: str, bot: 'Bot', update_queue: Queue):
+        self.shared_objects = {"bot": bot, "update_queue": update_queue}
+        handlers = [(rf"{webhook_path}/?", WebhookHandler, self.shared_objects)]  # noqa
+        tornado.web.Application.__init__(self, handlers)
+
+    def log_request(self, handler: tornado.web.RequestHandler) -> None:
+        pass
+
+
+# WebhookHandler, process webhook calls
+# pylint: disable=W0223
+class WebhookHandler(tornado.web.RequestHandler):
+    SUPPORTED_METHODS = ["POST"]
+
+    def __init__(
+        self,
+        application: tornado.web.Application,
+        request: httputil.HTTPServerRequest,
+        **kwargs: JSONDict,
+    ):
+        super().__init__(application, request, **kwargs)
+        self.logger = logging.getLogger(__name__)
+
+    def initialize(self, bot: 'Bot', update_queue: Queue) -> None:
+        # pylint: disable=W0201
+        self.bot = bot
+        self.update_queue = update_queue
+
+    def set_default_headers(self) -> None:
+        self.set_header("Content-Type", 'application/json; charset="utf-8"')
+
+    def post(self) -> None:
+        self.logger.debug('Webhook triggered')
+        self._validate_post()
+        json_string = self.request.body.decode()
+        data = json.loads(json_string)
+        self.set_status(200)
+        self.logger.debug('Webhook received data: %s', json_string)
+        update = Update.de_json(data, self.bot)
+        if update:
+            self.logger.debug('Received Update with ID %d on Webhook', update.update_id)
+            self.update_queue.put(update)
+
+    def _validate_post(self) -> None:
+        ct_header = self.request.headers.get("Content-Type", None)
+        if ct_header != 'application/json':
+            raise tornado.web.HTTPError(403)
+
+    def write_error(self, status_code: int, **kwargs: Any) -> None:
+        """Log an arbitrary message.
+
+        This is used by all other logging functions.
+
+        It overrides ``BaseHTTPRequestHandler.log_message``, which logs to ``sys.stderr``.
+
+        The first argument, FORMAT, is a format string for the message to be logged.  If the format
+        string contains any % escapes requiring parameters, they should be specified as subsequent
+        arguments (it's just like printf!).
+
+        The client ip is prefixed to every message.
+
+        """
+        super().write_error(status_code, **kwargs)
+        self.logger.debug(
+            "%s - - %s",
+            self.request.remote_ip,
+            "Exception in WebhookHandler",
+            exc_info=kwargs['exc_info'],
+        )

telegram/files/animation.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -17,11 +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 Animation."""
-from telegram import PhotoSize
-from telegram import TelegramObject
+from typing import TYPE_CHECKING, Any, Optional
 
+from telegram import PhotoSize, TelegramObject
 from telegram.utils.types import JSONDict
-from typing import Any, Optional, TYPE_CHECKING
+
 if TYPE_CHECKING:
     from telegram import Bot, File
 
@@ -32,20 +32,6 @@ class Animation(TelegramObject):
     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.
 
-    Attributes:
-        file_id (:obj:`str`): File identifier.
-        file_unique_id (:obj:`str`): Unique identifier for this file, which
-            is supposed to be the same over time and for different bots.
-            Can't be used to download or reuse the file.
-        width (:obj:`int`): Video width as defined by sender.
-        height (:obj:`int`): Video height as defined by sender.
-        duration (:obj:`int`): Duration of the video in seconds as defined by sender.
-        thumb (:class:`telegram.PhotoSize`): Optional. Animation thumbnail as defined by sender.
-        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.
-        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
-
     Args:
         file_id (:obj:`str`): Identifier for this file, which can be used to download
             or reuse the file.
@@ -62,20 +48,36 @@ class Animation(TelegramObject):
         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.
+        file_unique_id (:obj:`str`): Unique identifier for this file, which
+            is supposed to be the same over time and for different bots.
+            Can't be used to download or reuse the file.
+        width (:obj:`int`): Video width as defined by sender.
+        height (:obj:`int`): Video height as defined by sender.
+        duration (:obj:`int`): Duration of the video in seconds as defined by sender.
+        thumb (:class:`telegram.PhotoSize`): Optional. Animation thumbnail as defined by sender.
+        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.
+        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
+
     """
 
-    def __init__(self,
-                 file_id: str,
-                 file_unique_id: str,
-                 width: int,
-                 height: int,
-                 duration: int,
-                 thumb: PhotoSize = None,
-                 file_name: str = None,
-                 mime_type: str = None,
-                 file_size: int = None,
-                 bot: 'Bot' = None,
-                 **kwargs: Any):
+    def __init__(
+        self,
+        file_id: str,
+        file_unique_id: str,
+        width: int,
+        height: int,
+        duration: int,
+        thumb: PhotoSize = None,
+        file_name: str = None,
+        mime_type: str = None,
+        file_size: int = None,
+        bot: 'Bot' = None,
+        **_kwargs: Any,
+    ):
         # Required
         self.file_id = str(file_id)
         self.file_unique_id = str(file_unique_id)
@@ -102,21 +104,16 @@ class Animation(TelegramObject):
 
         return cls(bot=bot, **data)
 
-    def get_file(self, timeout: int = None, api_kwargs: JSONDict = None) -> 'File':
+    def get_file(self, timeout: float = None, api_kwargs: JSONDict = None) -> 'File':
         """Convenience wrapper over :attr:`telegram.Bot.get_file`
 
-        Args:
-            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
-                the read timeout from the server (instead of the one specified during creation of
-                the connection pool).
-            api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the
-                Telegram API.
+        For the documentation of the arguments, please see :meth:`telegram.Bot.get_file`.
 
         Returns:
             :class:`telegram.File`
 
         Raises:
-            :class:`telegram.TelegramError`
+            :class:`telegram.error.TelegramError`
 
         """
-        return self.bot.get_file(self.file_id, timeout=timeout, api_kwargs=api_kwargs)
+        return self.bot.get_file(file_id=self.file_id, timeout=timeout, api_kwargs=api_kwargs)

telegram/files/audio.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,10 +18,11 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram Audio."""
 
-from telegram import TelegramObject, PhotoSize
+from typing import TYPE_CHECKING, Any, Optional
 
+from telegram import PhotoSize, TelegramObject
 from telegram.utils.types import JSONDict
-from typing import Any, Optional, TYPE_CHECKING
+
 if TYPE_CHECKING:
     from telegram import Bot, File
 
@@ -32,21 +33,6 @@ class Audio(TelegramObject):
     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.
 
-    Attributes:
-        file_id (:obj:`str`): Identifier for this file.
-        file_unique_id (:obj:`str`): Unique identifier for this file, which
-            is supposed to be the same over time and for different bots.
-            Can't be used to download or reuse the file.
-        duration (:obj:`int`): Duration of the audio in seconds.
-        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.
-        mime_type (:obj:`str`): Optional. MIME type of the file as defined by sender.
-        file_size (:obj:`int`): Optional. File size.
-        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.
-
     Args:
         file_id (:obj:`str`): Identifier for this file, which can be used to download
             or reuse the file.
@@ -56,6 +42,7 @@ class Audio(TelegramObject):
         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.
+        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.
         thumb (:class:`telegram.PhotoSize`, optional): Thumbnail of the album cover to
@@ -63,19 +50,38 @@ class Audio(TelegramObject):
         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.
+        file_unique_id (:obj:`str`): Unique identifier for this file, which
+            is supposed to be the same over time and for different bots.
+            Can't be used to download or reuse the file.
+        duration (:obj:`int`): Duration of the audio in seconds.
+        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.
+        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.
+        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.
+
     """
 
-    def __init__(self,
-                 file_id: str,
-                 file_unique_id: str,
-                 duration: int,
-                 performer: str = None,
-                 title: str = None,
-                 mime_type: str = None,
-                 file_size: int = None,
-                 thumb: PhotoSize = None,
-                 bot: 'Bot' = None,
-                 **kwargs: Any):
+    def __init__(
+        self,
+        file_id: str,
+        file_unique_id: str,
+        duration: int,
+        performer: str = None,
+        title: str = None,
+        mime_type: str = None,
+        file_size: int = None,
+        thumb: PhotoSize = None,
+        bot: 'Bot' = None,
+        file_name: str = None,
+        **_kwargs: Any,
+    ):
         # Required
         self.file_id = str(file_id)
         self.file_unique_id = str(file_unique_id)
@@ -83,6 +89,7 @@ class Audio(TelegramObject):
         # Optionals
         self.performer = performer
         self.title = title
+        self.file_name = file_name
         self.mime_type = mime_type
         self.file_size = file_size
         self.thumb = thumb
@@ -101,21 +108,16 @@ class Audio(TelegramObject):
 
         return cls(bot=bot, **data)
 
-    def get_file(self, timeout: int = None, api_kwargs: JSONDict = None) -> 'File':
+    def get_file(self, timeout: float = None, api_kwargs: JSONDict = None) -> 'File':
         """Convenience wrapper over :attr:`telegram.Bot.get_file`
 
-        Args:
-            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
-                the read timeout from the server (instead of the one specified during creation of
-                the connection pool).
-            api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the
-                Telegram API.
+        For the documentation of the arguments, please see :meth:`telegram.Bot.get_file`.
 
         Returns:
             :class:`telegram.File`
 
         Raises:
-            :class:`telegram.TelegramError`
+            :class:`telegram.error.TelegramError`
 
         """
-        return self.bot.get_file(self.file_id, timeout=timeout, api_kwargs=api_kwargs)
+        return self.bot.get_file(file_id=self.file_id, timeout=timeout, api_kwargs=api_kwargs)

telegram/files/chatphoto.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -17,9 +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 ChatPhoto."""
-from telegram import TelegramObject
+from typing import TYPE_CHECKING, Any
+
+from telegram import TelegramObject
+from telegram.utils.types import JSONDict
 
-from typing import Any, TYPE_CHECKING
 if TYPE_CHECKING:
     from telegram import Bot, File
 
@@ -31,19 +33,6 @@ class ChatPhoto(TelegramObject):
     considered equal, if their :attr:`small_file_unique_id` and :attr:`big_file_unique_id` are
     equal.
 
-    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
-            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.
-            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
-            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.
-            Can't be used to download or reuse the file.
     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
@@ -59,15 +48,31 @@ class ChatPhoto(TelegramObject):
         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
+            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.
+            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
+            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.
+            Can't be used to download or reuse the file.
+
     """
 
-    def __init__(self,
-                 small_file_id: str,
-                 small_file_unique_id: str,
-                 big_file_id: str,
-                 big_file_unique_id: str,
-                 bot: 'Bot' = None,
-                 **kwargs: Any):
+    def __init__(
+        self,
+        small_file_id: str,
+        small_file_unique_id: str,
+        big_file_id: str,
+        big_file_unique_id: str,
+        bot: 'Bot' = None,
+        **_kwargs: Any,
+    ):
         self.small_file_id = small_file_id
         self.small_file_unique_id = small_file_unique_id
         self.big_file_id = big_file_id
@@ -75,44 +80,39 @@ class ChatPhoto(TelegramObject):
 
         self.bot = bot
 
-        self._id_attrs = (self.small_file_unique_id, self.big_file_unique_id,)
+        self._id_attrs = (
+            self.small_file_unique_id,
+            self.big_file_unique_id,
+        )
 
-    def get_small_file(self, timeout: int = None, **kwargs: Any) -> 'File':
+    def get_small_file(self, timeout: float = None, api_kwargs: JSONDict = None) -> 'File':
         """Convenience wrapper over :attr:`telegram.Bot.get_file` for getting the
         small (160x160) chat photo
 
-        Args:
-            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
-                the read timeout from the server (instead of the one specified during creation of
-                the connection pool).
-            api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the
-                Telegram API.
+        For the documentation of the arguments, please see :meth:`telegram.Bot.get_file`.
 
         Returns:
             :class:`telegram.File`
 
         Raises:
-            :class:`telegram.TelegramError`
+            :class:`telegram.error.TelegramError`
 
         """
-        return self.bot.get_file(self.small_file_id, timeout=timeout, **kwargs)
+        return self.bot.get_file(
+            file_id=self.small_file_id, timeout=timeout, api_kwargs=api_kwargs
+        )
 
-    def get_big_file(self, timeout: int = None, **kwargs: Any) -> 'File':
+    def get_big_file(self, timeout: float = None, api_kwargs: JSONDict = None) -> 'File':
         """Convenience wrapper over :attr:`telegram.Bot.get_file` for getting the
         big (640x640) chat photo
 
-        Args:
-            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
-                the read timeout from the server (instead of the one specified during creation of
-                the connection pool).
-            api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the
-                Telegram API.
+        For the documentation of the arguments, please see :meth:`telegram.Bot.get_file`.
 
         Returns:
             :class:`telegram.File`
 
         Raises:
-            :class:`telegram.TelegramError`
+            :class:`telegram.error.TelegramError`
 
         """
-        return self.bot.get_file(self.big_file_id, timeout=timeout, **kwargs)
+        return self.bot.get_file(file_id=self.big_file_id, timeout=timeout, api_kwargs=api_kwargs)

telegram/files/contact.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,9 +18,10 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram Contact."""
 
-from telegram import TelegramObject
 from typing import Any
 
+from telegram import TelegramObject
+
 
 class Contact(TelegramObject):
     """This object represents a phone contact.
@@ -28,13 +29,6 @@ class Contact(TelegramObject):
     Objects of this class are comparable in terms of equality. Two objects of this class are
     considered equal, if their :attr:`phone_number` is equal.
 
-    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.
-        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.
-
     Args:
         phone_number (:obj:`str`): Contact's phone number.
         first_name (:obj:`str`): Contact's first name.
@@ -43,15 +37,24 @@ class Contact(TelegramObject):
         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.
+        first_name (:obj:`str`): Contact's first name.
+        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.
+
     """
 
-    def __init__(self,
-                 phone_number: str,
-                 first_name: str,
-                 last_name: str = None,
-                 user_id: int = None,
-                 vcard: str = None,
-                 **kwargs: Any):
+    def __init__(
+        self,
+        phone_number: str,
+        first_name: str,
+        last_name: str = None,
+        user_id: int = None,
+        vcard: str = None,
+        **_kwargs: Any,
+    ):
         # Required
         self.phone_number = str(phone_number)
         self.first_name = first_name

telegram/files/document.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,10 +18,11 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram Document."""
 
-from telegram import PhotoSize, TelegramObject
+from typing import TYPE_CHECKING, Any, Optional
 
+from telegram import PhotoSize, TelegramObject
 from telegram.utils.types import JSONDict
-from typing import Any, Optional, TYPE_CHECKING
+
 if TYPE_CHECKING:
     from telegram import Bot, File
 
@@ -33,17 +34,6 @@ class Document(TelegramObject):
     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.
 
-    Attributes:
-        file_id (:obj:`str`): File identifier.
-        file_unique_id (:obj:`str`): Unique identifier for this file, which
-            is supposed to be the same over time and for different bots.
-            Can't be used to download or reuse the file.
-        thumb (:class:`telegram.PhotoSize`): Optional. Document thumbnail.
-        file_name (:obj:`str`): Original filename.
-        mime_type (:obj:`str`): Optional. MIME type of the file.
-        file_size (:obj:`int`): Optional. File size.
-        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
-
     Args:
         file_id (:obj:`str`): Identifier for this file, which can be used to download
             or reuse the file.
@@ -56,18 +46,32 @@ class Document(TelegramObject):
         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.
+        file_unique_id (:obj:`str`): Unique identifier for this file, which
+            is supposed to be the same over time and for different bots.
+            Can't be used to download or reuse the file.
+        thumb (:class:`telegram.PhotoSize`): Optional. Document thumbnail.
+        file_name (:obj:`str`): Original filename.
+        mime_type (:obj:`str`): Optional. MIME type of the file.
+        file_size (:obj:`int`): Optional. File size.
+        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
+
     """
+
     _id_keys = ('file_id',)
 
-    def __init__(self,
-                 file_id: str,
-                 file_unique_id: str,
-                 thumb: PhotoSize = None,
-                 file_name: str = None,
-                 mime_type: str = None,
-                 file_size: int = None,
-                 bot: 'Bot' = None,
-                 **kwargs: Any):
+    def __init__(
+        self,
+        file_id: str,
+        file_unique_id: str,
+        thumb: PhotoSize = None,
+        file_name: str = None,
+        mime_type: str = None,
+        file_size: int = None,
+        bot: 'Bot' = None,
+        **_kwargs: Any,
+    ):
         # Required
         self.file_id = str(file_id)
         self.file_unique_id = str(file_unique_id)
@@ -91,21 +95,16 @@ class Document(TelegramObject):
 
         return cls(bot=bot, **data)
 
-    def get_file(self, timeout: int = None, api_kwargs: JSONDict = None) -> 'File':
+    def get_file(self, timeout: float = None, api_kwargs: JSONDict = None) -> 'File':
         """Convenience wrapper over :attr:`telegram.Bot.get_file`
 
-        Args:
-            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
-                the read timeout from the server (instead of the one specified during creation of
-                the connection pool).
-            api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the
-                Telegram API.
+        For the documentation of the arguments, please see :meth:`telegram.Bot.get_file`.
 
         Returns:
             :class:`telegram.File`
 
         Raises:
-            :class:`telegram.TelegramError`
+            :class:`telegram.error.TelegramError`
 
         """
-        return self.bot.get_file(self.file_id, timeout=timeout, api_kwargs=api_kwargs)
+        return self.bot.get_file(file_id=self.file_id, timeout=timeout, api_kwargs=api_kwargs)

telegram/files/file.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -17,16 +17,17 @@
 # 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 File."""
+import os
+import shutil
+import urllib.parse as urllib_parse
 from base64 import b64decode
 from os.path import basename
-import os
-
-import urllib.parse as urllib_parse
+from typing import IO, TYPE_CHECKING, Any, Optional, Union
 
 from telegram import TelegramObject
 from telegram.passport.credentials import decrypt
+from telegram.utils.helpers import is_local_file
 
-from typing import Any, Optional, IO, Union, TYPE_CHECKING
 if TYPE_CHECKING:
     from telegram import Bot, FileCredentials
 
@@ -41,15 +42,9 @@ class File(TelegramObject):
     considered equal, if their :attr:`file_unique_id` is equal.
 
     Note:
-        Maximum file size to download is 20 MB.
-
-    Attributes:
-        file_id (:obj:`str`): Identifier for this file.
-        file_unique_id (:obj:`str`): Unique identifier for this file, which
-            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.
-        file_path (:obj:`str`): Optional. File path. Use :attr:`download` to get the file.
+        * Maximum file size to download is 20 MB.
+        * 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 :attr:`download()`.
 
     Args:
         file_id (:obj:`str`): Identifier for this file, which can be used to download
@@ -62,19 +57,25 @@ class File(TelegramObject):
         bot (:obj:`telegram.Bot`, optional): Bot to use with shortcut method.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
-    Note:
-        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 :attr:`download()`.
+    Attributes:
+        file_id (:obj:`str`): Identifier for this file.
+        file_unique_id (:obj:`str`): Unique identifier for this file, which
+            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.
+        file_path (:obj:`str`): Optional. File path. Use :attr:`download` to get the file.
 
     """
 
-    def __init__(self,
-                 file_id: str,
-                 file_unique_id: str,
-                 bot: 'Bot' = None,
-                 file_size: int = None,
-                 file_path: str = None,
-                 **kwargs: Any):
+    def __init__(
+        self,
+        file_id: str,
+        file_unique_id: str,
+        bot: 'Bot' = None,
+        file_size: int = None,
+        file_path: str = None,
+        **_kwargs: Any,
+    ):
         # Required
         self.file_id = str(file_id)
         self.file_unique_id = str(file_unique_id)
@@ -86,10 +87,9 @@ class File(TelegramObject):
 
         self._id_attrs = (self.file_unique_id,)
 
-    def download(self,
-                 custom_path: str = None,
-                 out: IO = None,
-                 timeout: int = None) -> Union[str, IO]:
+    def download(
+        self, custom_path: str = None, out: IO = None, timeout: int = None
+    ) -> Union[str, IO]:
         """
         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
@@ -98,7 +98,10 @@ class File(TelegramObject):
         the ``out.write`` method.
 
         Note:
-            :attr:`custom_path` and :attr:`out` are mutually exclusive.
+            * :attr:`custom_path` and :attr:`out` are mutually exclusive.
+            * If neither :attr:`custom_path` nor :attr:`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.
 
         Args:
             custom_path (:obj:`str`, optional): Custom path.
@@ -110,7 +113,7 @@ class File(TelegramObject):
 
         Returns:
             :obj:`str` | :obj:`io.BufferedWriter`: The same object as :attr:`out` if specified.
-            Otherwise, returns the filename downloaded to.
+            Otherwise, returns the filename downloaded to or the file path of the local file.
 
         Raises:
             ValueError: If both :attr:`custom_path` and :attr:`out` are passed.
@@ -119,39 +122,57 @@ class File(TelegramObject):
         if custom_path is not None and out is not None:
             raise ValueError('custom_path and out are mutually exclusive')
 
-        # Convert any UTF-8 char into a url encoded ASCII string.
-        url = self._get_encoded_url()
+        local_file = is_local_file(self.file_path)
+
+        if local_file:
+            url = self.file_path
+        else:
+            # Convert any UTF-8 char into a url encoded ASCII string.
+            url = self._get_encoded_url()
 
         if out:
-            buf = self.bot.request.retrieve(url)
-            if self._credentials:
-                buf = decrypt(b64decode(self._credentials.secret),
-                              b64decode(self._credentials.hash),
-                              buf)
+            if local_file:
+                with open(url, 'rb') as file:
+                    buf = file.read()
+            else:
+                buf = self.bot.request.retrieve(url)
+                if self._credentials:
+                    buf = decrypt(
+                        b64decode(self._credentials.secret), b64decode(self._credentials.hash), buf
+                    )
             out.write(buf)
             return out
-        else:
-            if custom_path:
-                filename = custom_path
-            elif self.file_path:
-                filename = basename(self.file_path)
-            else:
-                filename = os.path.join(os.getcwd(), self.file_id)
 
-            buf = self.bot.request.retrieve(url, timeout=timeout)
-            if self._credentials:
-                buf = decrypt(b64decode(self._credentials.secret),
-                              b64decode(self._credentials.hash),
-                              buf)
-            with open(filename, 'wb') as fobj:
-                fobj.write(buf)
-            return filename
+        if custom_path and local_file:
+            shutil.copyfile(self.file_path, custom_path)
+            return custom_path
+
+        if custom_path:
+            filename = custom_path
+        elif local_file:
+            return self.file_path
+        elif self.file_path:
+            filename = basename(self.file_path)
+        else:
+            filename = os.path.join(os.getcwd(), self.file_id)
+
+        buf = self.bot.request.retrieve(url, timeout=timeout)
+        if self._credentials:
+            buf = decrypt(
+                b64decode(self._credentials.secret), b64decode(self._credentials.hash), buf
+            )
+        with open(filename, 'wb') as fobj:
+            fobj.write(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(self.file_path)
-        return urllib_parse.urlunsplit(urllib_parse.SplitResult(
-            sres.scheme, sres.netloc, urllib_parse.quote(sres.path), sres.query, sres.fragment))
+        return urllib_parse.urlunsplit(
+            urllib_parse.SplitResult(
+                sres.scheme, sres.netloc, urllib_parse.quote(sres.path), sres.query, sres.fragment
+            )
+        )
 
     def download_as_bytearray(self, buf: bytearray = None) -> bytes:
         """Download this file and return it as a bytearray.
@@ -166,8 +187,11 @@ class File(TelegramObject):
         """
         if buf is None:
             buf = bytearray()
-
-        buf.extend(self.bot.request.retrieve(self._get_encoded_url()))
+        if is_local_file(self.file_path):
+            with open(self.file_path, "rb") as file:
+                buf.extend(file.read())
+        else:
+            buf.extend(self.bot.request.retrieve(self._get_encoded_url()))
         return buf
 
     def set_credentials(self, credentials: 'FileCredentials') -> None:

telegram/files/inputfile.py

@@ -2,7 +2,7 @@
 # pylint: disable=W0622,E0611
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -20,27 +20,22 @@
 """This module contains an object that represents a Telegram InputFile."""
 
 import imghdr
+import logging
 import mimetypes
 import os
+from typing import IO, Optional, Tuple, Union
 from uuid import uuid4
 
-from telegram import TelegramError
-
-from typing import IO, Tuple, Optional
-
 DEFAULT_MIME_TYPE = 'application/octet-stream'
+logger = logging.getLogger(__name__)
 
 
 class InputFile:
     """This object represents a Telegram InputFile.
 
-    Attributes:
-        input_file_content (:obj:`bytes`): The binary content of the file to send.
-        filename (:obj:`str`): Optional. Filename for the file to be sent.
-        attach (:obj:`str`): Optional. Attach id for sending multiple files.
-
     Args:
-        obj (:obj:`File handler`): An open file descriptor.
+        obj (:obj:`File handler` | :obj:`bytes`): An open file descriptor or the files content as
+            bytes.
         filename (:obj:`str`, optional): Filename for this InputFile.
         attach (:obj:`bool`, optional): Whether this should be send as one file or is part of a
             collection of files.
@@ -48,26 +43,34 @@ class InputFile:
     Raises:
         TelegramError
 
+    Attributes:
+        input_file_content (:obj:`bytes`): The binary content of the file to send.
+        filename (:obj:`str`): Optional. Filename for the file to be sent.
+        attach (:obj:`str`): Optional. Attach id for sending multiple files.
+
     """
 
-    def __init__(self, obj: IO, filename: str = None, attach: bool = None):
+    def __init__(self, obj: Union[IO, bytes], filename: str = None, attach: bool = None):
         self.filename = None
-        self.input_file_content = obj.read()
+        if isinstance(obj, bytes):
+            self.input_file_content = obj
+        else:
+            self.input_file_content = obj.read()
         self.attach = 'attached' + uuid4().hex if attach else None
 
         if filename:
             self.filename = filename
-        elif (hasattr(obj, 'name') and not isinstance(obj.name, int)):
-            self.filename = os.path.basename(obj.name)
+        elif hasattr(obj, 'name') and not isinstance(obj.name, int):  # type: ignore[union-attr]
+            self.filename = os.path.basename(obj.name)  # type: ignore[union-attr]
+
+        image_mime_type = self.is_image(self.input_file_content)
+        if image_mime_type:
+            self.mimetype = image_mime_type
+        elif self.filename:
+            self.mimetype = mimetypes.guess_type(self.filename)[0] or DEFAULT_MIME_TYPE
+        else:
+            self.mimetype = DEFAULT_MIME_TYPE
 
-        try:
-            self.mimetype = self.is_image(self.input_file_content)
-        except TelegramError:
-            if self.filename:
-                self.mimetype = mimetypes.guess_type(
-                    self.filename)[0] or DEFAULT_MIME_TYPE
-            else:
-                self.mimetype = DEFAULT_MIME_TYPE
         if not self.filename:
             self.filename = self.mimetype.replace('/', '.')
 
@@ -76,21 +79,27 @@ class InputFile:
         return self.filename, self.input_file_content, self.mimetype
 
     @staticmethod
-    def is_image(stream: bytes) -> str:
+    def is_image(stream: bytes) -> Optional[str]:
         """Check if the content file is an image by analyzing its headers.
 
         Args:
             stream (:obj:`bytes`): A byte stream representing the content of a file.
 
         Returns:
-            :obj:`str`: The str mime-type of an image.
+            :obj:`str` | :obj:`None`: The mime-type of an image, if the input is an image, or
+            :obj:`None` else.
 
         """
-        image = imghdr.what(None, stream)
-        if image:
-            return 'image/%s' % image
-
-        raise TelegramError('Could not parse file content')
+        try:
+            image = imghdr.what(None, stream)
+            if image:
+                return f'image/{image}'
+            return None
+        except Exception:
+            logger.debug(
+                "Could not parse file content. Assuming that file is not an image.", exc_info=True
+            )
+            return None
 
     @staticmethod
     def is_file(obj: object) -> bool:

telegram/files/inputmedia.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,12 +18,20 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """Base class for Telegram InputMedia Objects."""
 
-from telegram import TelegramObject, InputFile, PhotoSize, Animation, Video, Audio, Document
-from telegram.utils.helpers import DEFAULT_NONE, DefaultValue
+from typing import Union, List, Tuple
 
-from typing import Union, IO, cast
-
-from telegram.utils.types import FileLike
+from telegram import (
+    Animation,
+    Audio,
+    Document,
+    InputFile,
+    PhotoSize,
+    TelegramObject,
+    Video,
+    MessageEntity,
+)
+from telegram.utils.helpers import DEFAULT_NONE, DefaultValue, parse_file_input
+from telegram.utils.types import FileInput, JSONDict
 
 
 class InputMedia(TelegramObject):
@@ -34,56 +42,88 @@ class InputMedia(TelegramObject):
     :class:`telegram.InputMediaVideo` for detailed use.
 
     """
-    pass
+
+    caption_entities: Union[List[MessageEntity], Tuple[MessageEntity, ...], None] = None
+
+    def to_dict(self) -> JSONDict:
+        data = super().to_dict()
+
+        if self.caption_entities:
+            data['caption_entities'] = [
+                ce.to_dict() for ce in self.caption_entities  # pylint: disable=E1133
+            ]
+
+        return data
 
 
 class InputMediaAnimation(InputMedia):
     """Represents an animation file (GIF or H.264/MPEG-4 AVC video without sound) to be sent.
 
+    Note:
+        When using a :class:`telegram.Animation` for the :attr:`media` attribute. It will take the
+        width, height and duration from that video, unless otherwise specified with the optional
+        arguments.
+
+    Args:
+        media (:obj:`str` | `filelike 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.
+
+            .. versionchanged:: 13.2
+               Accept :obj:`bytes` as input.
+        filename (:obj:`str`, optional): Custom file name for the animation, when uploading a
+            new file. Convenience parameter, useful e.g. when sending files generated by the
+            :obj:`tempfile` module.
+
+                .. versionadded:: 13.1
+        thumb (`filelike 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.
+
+            .. versionchanged:: 13.2
+               Accept :obj:`bytes` as input.
+        caption (:obj:`str`, optional): Caption of the animation to be sent, 0-1024 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.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 parse_mode.
+        width (:obj:`int`, optional): Animation width.
+        height (:obj:`int`, optional): Animation height.
+        duration (:obj:`int`, optional): Animation duration.
+
     Attributes:
         type (:obj:`str`): ``animation``.
         media (:obj:`str` | :class:`telegram.InputFile`): Animation to send.
         caption (:obj:`str`): Optional. Caption of the document to be sent.
         parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting.
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
+            entities that appear in the caption.
         thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send.
         width (:obj:`int`): Optional. Animation width.
         height (:obj:`int`): Optional. Animation height.
         duration (:obj:`int`): Optional. Animation duration.
 
-
-    Args:
-        media (:obj:`str` | `filelike object` | :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.
-        thumb (`filelike object`, 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.
-        caption (:obj:`str`, optional): Caption of the animation to be sent, 0-1024 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.ParseMode` for the available modes.
-        width (:obj:`int`, optional): Animation width.
-        height (:obj:`int`, optional): Animation height.
-        duration (:obj:`int`, optional): Animation duration.
-
-    Note:
-        When using a :class:`telegram.Animation` for the :attr:`media` attribute. It will take the
-        width, height and duration from that video, unless otherwise specified with the optional
-        arguments.
     """
 
-    def __init__(self,
-                 media: Union[str, FileLike, Animation],
-                 thumb: FileLike = None,
-                 caption: str = None,
-                 parse_mode: Union[str, DefaultValue] = DEFAULT_NONE,
-                 width: int = None,
-                 height: int = None,
-                 duration: int = None):
+    def __init__(
+        self,
+        media: Union[FileInput, Animation],
+        thumb: FileInput = None,
+        caption: str = None,
+        parse_mode: Union[str, DefaultValue] = DEFAULT_NONE,
+        width: int = None,
+        height: int = None,
+        duration: int = None,
+        caption_entities: Union[List[MessageEntity], Tuple[MessageEntity, ...]] = None,
+        filename: str = None,
+    ):
         self.type = 'animation'
 
         if isinstance(media, Animation):
@@ -91,22 +131,16 @@ class InputMediaAnimation(InputMedia):
             self.width = media.width
             self.height = media.height
             self.duration = media.duration
-        elif InputFile.is_file(media):
-            media = cast(IO, media)
-            self.media = InputFile(media, attach=True)
         else:
-            self.media = media  # type: ignore[assignment]
+            self.media = parse_file_input(media, attach=True, filename=filename)
 
         if thumb:
-            if InputFile.is_file(thumb):
-                thumb = cast(IO, thumb)
-                self.thumb = InputFile(thumb, attach=True)
-            else:
-                self.thumb = thumb  # type: ignore[assignment]
+            self.thumb = parse_file_input(thumb, attach=True)
 
         if caption:
             self.caption = caption
         self.parse_mode = parse_mode
+        self.caption_entities = caption_entities
         if width:
             self.width = width
         if height:
@@ -118,79 +152,58 @@ class InputMediaAnimation(InputMedia):
 class InputMediaPhoto(InputMedia):
     """Represents a photo to be sent.
 
-    Attributes:
-        type (:obj:`str`): ``photo``.
-        media (:obj:`str` | :class:`telegram.InputFile`): Photo to send.
-        caption (:obj:`str`): Optional. Caption of the document to be sent.
-        parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting.
-
     Args:
-        media (:obj:`str` | `filelike object` | :class:`telegram.PhotoSize`): File to send. Pass a
+        media (:obj:`str` | `filelike 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.
+
+            .. versionchanged:: 13.2
+               Accept :obj:`bytes` as input.
+        filename (:obj:`str`, optional): Custom file name for the photo, when uploading a
+            new file. Convenience parameter, useful e.g. when sending files generated by the
+            :obj:`tempfile` module.
+
+                .. versionadded:: 13.1
         caption (:obj:`str`, optional ): Caption of the photo to be sent, 0-1024 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.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 parse_mode.
+
+    Attributes:
+        type (:obj:`str`): ``photo``.
+        media (:obj:`str` | :class:`telegram.InputFile`): Photo to send.
+        caption (:obj:`str`): Optional. Caption of the document to be sent.
+        parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting.
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
+            entities that appear in the caption.
+
     """
 
-    def __init__(self,
-                 media: Union[str, FileLike, PhotoSize],
-                 caption: str = None,
-                 parse_mode: Union[str, DefaultValue] = DEFAULT_NONE):
+    def __init__(
+        self,
+        media: Union[FileInput, PhotoSize],
+        caption: str = None,
+        parse_mode: Union[str, DefaultValue] = DEFAULT_NONE,
+        caption_entities: Union[List[MessageEntity], Tuple[MessageEntity, ...]] = None,
+        filename: str = None,
+    ):
         self.type = 'photo'
-
-        if isinstance(media, PhotoSize):
-            self.media: Union[str, InputFile] = media.file_id
-        elif InputFile.is_file(media):
-            media = cast(IO, media)
-            self.media = InputFile(media, attach=True)
-        else:
-            self.media = media  # type: ignore[assignment]
+        self.media = parse_file_input(media, PhotoSize, attach=True, filename=filename)
 
         if caption:
             self.caption = caption
         self.parse_mode = parse_mode
+        self.caption_entities = caption_entities
 
 
 class InputMediaVideo(InputMedia):
     """Represents a video to be sent.
 
-    Attributes:
-        type (:obj:`str`): ``video``.
-        media (:obj:`str` | :class:`telegram.InputFile`): Video file to send.
-        caption (:obj:`str`): Optional. Caption of the document to be sent.
-        parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting.
-        width (:obj:`int`): Optional. Video width.
-        height (:obj:`int`): Optional. Video height.
-        duration (:obj:`int`): Optional. Video duration.
-        supports_streaming (:obj:`bool`): Optional. Pass :obj:`True`, if the uploaded video is
-            suitable for streaming.
-        thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send.
-
-    Args:
-        media (:obj:`str` | `filelike object` | :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.
-        caption (:obj:`str`, optional): Caption of the video to be sent, 0-1024 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.ParseMode` for the available modes.
-        width (:obj:`int`, optional): Video width.
-        height (:obj:`int`, optional): Video height.
-        duration (:obj:`int`, optional): Video duration.
-        supports_streaming (:obj:`bool`, optional): Pass :obj:`True`, if the uploaded video is
-            suitable for streaming.
-        thumb (`filelike object`, 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.
-
     Note:
         *  When using a :class:`telegram.Video` for the :attr:`media` attribute. It will take the
            width, height and duration from that video, unless otherwise specified with the optional
@@ -198,17 +211,72 @@ class InputMediaVideo(InputMedia):
         *  ``thumb`` will be ignored for small video files, for which Telegram can easily
            generate thumb nails. However, this behaviour is undocumented and might be changed
            by Telegram.
+
+    Args:
+        media (:obj:`str` | `filelike 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.
+
+            .. versionchanged:: 13.2
+               Accept :obj:`bytes` as input.
+        filename (:obj:`str`, optional): Custom file name for the video, when uploading a
+            new file. Convenience parameter, useful e.g. when sending files generated by the
+            :obj:`tempfile` module.
+
+                .. versionadded:: 13.1
+        caption (:obj:`str`, optional): Caption of the video to be sent, 0-1024 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.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 parse_mode.
+        width (:obj:`int`, optional): Video width.
+        height (:obj:`int`, optional): Video height.
+        duration (:obj:`int`, optional): Video duration.
+        supports_streaming (:obj:`bool`, optional): Pass :obj:`True`, if the uploaded video is
+            suitable for streaming.
+        thumb (`filelike 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.
+
+            .. versionchanged:: 13.2
+               Accept :obj:`bytes` as input.
+
+    Attributes:
+        type (:obj:`str`): ``video``.
+        media (:obj:`str` | :class:`telegram.InputFile`): Video file to send.
+        caption (:obj:`str`): Optional. Caption of the document to be sent.
+        parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting.
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
+            entities that appear in the caption.
+        width (:obj:`int`): Optional. Video width.
+        height (:obj:`int`): Optional. Video height.
+        duration (:obj:`int`): Optional. Video duration.
+        supports_streaming (:obj:`bool`): Optional. Pass :obj:`True`, if the uploaded video is
+            suitable for streaming.
+        thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send.
+
     """
 
-    def __init__(self,
-                 media: Union[str, FileLike, Video],
-                 caption: str = None,
-                 width: int = None,
-                 height: int = None,
-                 duration: int = None,
-                 supports_streaming: bool = None,
-                 parse_mode: Union[str, DefaultValue] = DEFAULT_NONE,
-                 thumb: FileLike = None):
+    def __init__(
+        self,
+        media: Union[FileInput, Video],
+        caption: str = None,
+        width: int = None,
+        height: int = None,
+        duration: int = None,
+        supports_streaming: bool = None,
+        parse_mode: Union[str, DefaultValue] = DEFAULT_NONE,
+        thumb: FileInput = None,
+        caption_entities: Union[List[MessageEntity], Tuple[MessageEntity, ...]] = None,
+        filename: str = None,
+    ):
         self.type = 'video'
 
         if isinstance(media, Video):
@@ -216,22 +284,16 @@ class InputMediaVideo(InputMedia):
             self.width = media.width
             self.height = media.height
             self.duration = media.duration
-        elif InputFile.is_file(media):
-            media = cast(IO, media)
-            self.media = InputFile(media, attach=True)
         else:
-            self.media = media  # type: ignore[assignment]
+            self.media = parse_file_input(media, attach=True, filename=filename)
 
         if thumb:
-            if InputFile.is_file(thumb):
-                thumb = cast(IO, thumb)
-                self.thumb = InputFile(thumb, attach=True)
-            else:
-                self.thumb = thumb  # type: ignore[assignment]
+            self.thumb = parse_file_input(thumb, attach=True)
 
         if caption:
             self.caption = caption
         self.parse_mode = parse_mode
+        self.caption_entities = caption_entities
         if width:
             self.width = width
         if height:
@@ -245,51 +307,74 @@ class InputMediaVideo(InputMedia):
 class InputMediaAudio(InputMedia):
     """Represents an audio file to be treated as music to be sent.
 
+    Note:
+        When using a :class:`telegram.Audio` for the :attr:`media` attribute. It will take the
+        duration, performer and title from that video, unless otherwise specified with the
+        optional arguments.
+
+    Args:
+        media (:obj:`str` | `filelike 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.
+
+            .. versionchanged:: 13.2
+               Accept :obj:`bytes` as input.
+        filename (:obj:`str`, optional): Custom file name for the audio, when uploading a
+            new file. Convenience parameter, useful e.g. when sending files generated by the
+            :obj:`tempfile` module.
+
+                .. versionadded:: 13.1
+        caption (:obj:`str`, optional): Caption of the audio to be sent, 0-1024 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.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 parse_mode.
+        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 (`filelike 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.
+
+            .. versionchanged:: 13.2
+               Accept :obj:`bytes` as input.
+
     Attributes:
         type (:obj:`str`): ``audio``.
         media (:obj:`str` | :class:`telegram.InputFile`): Audio file to send.
         caption (:obj:`str`): Optional. Caption of the document to be sent.
         parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting.
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
+            entities that appear in the caption.
         duration (:obj:`int`): Duration of the audio in seconds.
         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 (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send.
 
-    Args:
-        media (:obj:`str` | `filelike object` | :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.
-        caption (:obj:`str`, optional): Caption of the audio to be sent, 0-1024 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.ParseMode` for the available modes.
-        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 (`filelike object`, 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.
-
-    Note:
-        When using a :class:`telegram.Audio` for the :attr:`media` attribute. It will take the
-        duration, performer and title from that video, unless otherwise specified with the
-        optional arguments.
     """
 
-    def __init__(self,
-                 media: Union[str, FileLike, Audio],
-                 thumb: FileLike = None,
-                 caption: str = None,
-                 parse_mode: Union[str, DefaultValue] = DEFAULT_NONE,
-                 duration: int = None,
-                 performer: str = None,
-                 title: str = None):
+    def __init__(
+        self,
+        media: Union[FileInput, Audio],
+        thumb: FileInput = None,
+        caption: str = None,
+        parse_mode: Union[str, DefaultValue] = DEFAULT_NONE,
+        duration: int = None,
+        performer: str = None,
+        title: str = None,
+        caption_entities: Union[List[MessageEntity], Tuple[MessageEntity, ...]] = None,
+        filename: str = None,
+    ):
         self.type = 'audio'
 
         if isinstance(media, Audio):
@@ -297,22 +382,16 @@ class InputMediaAudio(InputMedia):
             self.duration = media.duration
             self.performer = media.performer
             self.title = media.title
-        elif InputFile.is_file(media):
-            media = cast(IO, media)
-            self.media = InputFile(media, attach=True)
         else:
-            self.media = media  # type: ignore[assignment]
+            self.media = parse_file_input(media, attach=True, filename=filename)
 
         if thumb:
-            if InputFile.is_file(thumb):
-                thumb = cast(IO, thumb)
-                self.thumb = InputFile(thumb, attach=True)
-            else:
-                self.thumb = thumb  # type: ignore[assignment]
+            self.thumb = parse_file_input(thumb, attach=True)
 
         if caption:
             self.caption = caption
         self.parse_mode = parse_mode
+        self.caption_entities = caption_entities
         if duration:
             self.duration = duration
         if performer:
@@ -324,52 +403,72 @@ class InputMediaAudio(InputMedia):
 class InputMediaDocument(InputMedia):
     """Represents a general file to be sent.
 
-    Attributes:
-        type (:obj:`str`): ``document``.
-        media (:obj:`str` | :class:`telegram.InputFile`): File to send.
-        caption (:obj:`str`): Optional. Caption of the document to be sent.
-        parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting.
-        thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send.
-
     Args:
-        media (:obj:`str` | `filelike object` | :class:`telegram.Document`): File to send. Pass a
+        media (:obj:`str` | `filelike 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.
+
+            .. versionchanged:: 13.2
+               Accept :obj:`bytes` as input.
+        filename (:obj:`str`, optional): Custom file name for the document, when uploading a
+            new file. Convenience parameter, useful e.g. when sending files generated by the
+            :obj:`tempfile` module.
+
+                .. versionadded:: 13.1
         caption (:obj:`str`, optional): Caption of the document to be sent, 0-1024 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.ParseMode` for the available modes.
-        thumb (`filelike object`, optional): Thumbnail of the file sent; can be ignored if
+        caption_entities (List[:class:`telegram.MessageEntity`], optional): List of special
+            entities that appear in the caption, which can be specified instead of parse_mode.
+        thumb (`filelike 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.
+
+            .. versionchanged:: 13.2
+               Accept :obj:`bytes` as input.
+        disable_content_type_detection (:obj:`bool`, optional): Disables automatic server-side
+            content type detection for files uploaded using multipart/form-data. Always true, if
+            the document is sent as part of an album.
+
+    Attributes:
+        type (:obj:`str`): ``document``.
+        media (:obj:`str` | :class:`telegram.InputFile`): File to send.
+        caption (:obj:`str`): Optional. Caption of the document to be sent.
+        parse_mode (:obj:`str`): Optional. The parse mode to use for text formatting.
+        caption_entities (List[:class:`telegram.MessageEntity`]): Optional. List of special
+            entities that appear in the caption.
+        thumb (:class:`telegram.InputFile`): Optional. Thumbnail of the file to send.
+        disable_content_type_detection (:obj:`bool`): Optional. Disables automatic server-side
+            content type detection for files uploaded using multipart/form-data. Always true, if
+            the document is sent as part of an album.
+
     """
 
-    def __init__(self,
-                 media: Union[str, FileLike, Document],
-                 thumb: FileLike = None,
-                 caption: str = None,
-                 parse_mode: Union[str, DefaultValue] = DEFAULT_NONE):
+    def __init__(
+        self,
+        media: Union[FileInput, Document],
+        thumb: FileInput = None,
+        caption: str = None,
+        parse_mode: Union[str, DefaultValue] = DEFAULT_NONE,
+        disable_content_type_detection: bool = None,
+        caption_entities: Union[List[MessageEntity], Tuple[MessageEntity, ...]] = None,
+        filename: str = None,
+    ):
         self.type = 'document'
-
-        if isinstance(media, Document):
-            self.media: Union[str, InputFile] = media.file_id
-        elif InputFile.is_file(media):
-            media = cast(IO, media)
-            self.media = InputFile(media, attach=True)
-        else:
-            self.media = media  # type: ignore[assignment]
+        self.media = parse_file_input(media, Document, attach=True, filename=filename)
 
         if thumb:
-            if InputFile.is_file(thumb):
-                thumb = cast(IO, thumb)
-                self.thumb = InputFile(thumb, attach=True)
-            else:
-                self.thumb = thumb  # type: ignore[assignment]
+            self.thumb = parse_file_input(thumb, attach=True)
 
         if caption:
             self.caption = caption
         self.parse_mode = parse_mode
+        self.caption_entities = caption_entities
+        self.disable_content_type_detection = disable_content_type_detection

telegram/files/location.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,9 +18,10 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram Location."""
 
-from telegram import TelegramObject
 from typing import Any
 
+from telegram import TelegramObject
+
 
 class Location(TelegramObject):
     """This object represents a point on the map.
@@ -28,20 +29,53 @@ class Location(TelegramObject):
     Objects of this class are comparable in terms of equality. Two objects of this class are
     considered equal, if their :attr:`longitute` and :attr:`latitude` are equal.
 
-    Attributes:
-        longitude (:obj:`float`): Longitude as defined by sender.
-        latitude (:obj:`float`): Latitude as defined by sender.
-
     Args:
         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-1500.
+        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-360.
+            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.
+        latitude (:obj:`float`): Latitude as defined by sender.
+        horizontal_accuracy (:obj:`float`): Optional. The radius of uncertainty for the location,
+            measured in meters.
+        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.
+            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.
+
     """
 
-    def __init__(self, longitude: float, latitude: float, **kwargs: Any):
+    def __init__(
+        self,
+        longitude: float,
+        latitude: float,
+        horizontal_accuracy: float = None,
+        live_period: int = None,
+        heading: int = None,
+        proximity_alert_radius: int = None,
+        **_kwargs: Any,
+    ):
         # Required
         self.longitude = float(longitude)
         self.latitude = float(latitude)
 
+        # Optionals
+        self.horizontal_accuracy = float(horizontal_accuracy) if horizontal_accuracy else None
+        self.live_period = int(live_period) if live_period else None
+        self.heading = int(heading) if heading else None
+        self.proximity_alert_radius = (
+            int(proximity_alert_radius) if proximity_alert_radius else None
+        )
+
         self._id_attrs = (self.longitude, self.latitude)

telegram/files/photosize.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -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 PhotoSize."""
 
+from typing import TYPE_CHECKING, Any
+
 from telegram import TelegramObject
 from telegram.utils.types import JSONDict
-from typing import Any, TYPE_CHECKING
+
 if TYPE_CHECKING:
     from telegram import Bot, File
 
@@ -31,16 +33,6 @@ class PhotoSize(TelegramObject):
     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.
 
-    Attributes:
-        file_id (:obj:`str`): Identifier for this file.
-        file_unique_id (:obj:`str`): Unique identifier for this file, which
-            is supposed to be the same over time and for different bots.
-            Can't be used to download or reuse the file.
-        width (:obj:`int`): Photo width.
-        height (:obj:`int`): Photo height.
-        file_size (:obj:`int`): Optional. File size.
-        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
-
     Args:
         file_id (:obj:`str`): Identifier for this file, which can be used to download
             or reuse the file.
@@ -53,16 +45,28 @@ class PhotoSize(TelegramObject):
         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.
+        file_unique_id (:obj:`str`): Unique identifier for this file, which
+            is supposed to be the same over time and for different bots.
+            Can't be used to download or reuse the file.
+        width (:obj:`int`): Photo width.
+        height (:obj:`int`): Photo height.
+        file_size (:obj:`int`): Optional. File size.
+        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
+
     """
 
-    def __init__(self,
-                 file_id: str,
-                 file_unique_id: str,
-                 width: int,
-                 height: int,
-                 file_size: int = None,
-                 bot: 'Bot' = None,
-                 **kwargs: Any):
+    def __init__(
+        self,
+        file_id: str,
+        file_unique_id: str,
+        width: int,
+        height: int,
+        file_size: int = None,
+        bot: 'Bot' = None,
+        **_kwargs: Any,
+    ):
         # Required
         self.file_id = str(file_id)
         self.file_unique_id = str(file_unique_id)
@@ -74,21 +78,16 @@ class PhotoSize(TelegramObject):
 
         self._id_attrs = (self.file_unique_id,)
 
-    def get_file(self, timeout: int = None, api_kwargs: JSONDict = None) -> 'File':
+    def get_file(self, timeout: float = None, api_kwargs: JSONDict = None) -> 'File':
         """Convenience wrapper over :attr:`telegram.Bot.get_file`
 
-        Args:
-            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
-                the read timeout from the server (instead of the one specified during creation of
-                the connection pool).
-            api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the
-                Telegram API.
+        For the documentation of the arguments, please see :meth:`telegram.Bot.get_file`.
 
         Returns:
             :class:`telegram.File`
 
         Raises:
-            :class:`telegram.TelegramError`
+            :class:`telegram.error.TelegramError`
 
         """
-        return self.bot.get_file(self.file_id, timeout=timeout, api_kwargs=api_kwargs)
+        return self.bot.get_file(file_id=self.file_id, timeout=timeout, api_kwargs=api_kwargs)

telegram/files/sticker.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -18,9 +18,11 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains objects that represents stickers."""
 
-from telegram import PhotoSize, TelegramObject
+from typing import TYPE_CHECKING, Any, List, Optional, ClassVar
+
+from telegram import PhotoSize, TelegramObject, constants
 from telegram.utils.types import JSONDict
-from typing import Any, Optional, List, TYPE_CHECKING
+
 if TYPE_CHECKING:
     from telegram import Bot, File
 
@@ -31,23 +33,6 @@ class Sticker(TelegramObject):
     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.
 
-    Attributes:
-        file_id (:obj:`str`): Identifier for this file.
-        file_unique_id (:obj:`str`): Unique identifier for this file, which
-            is supposed to be the same over time and for different bots.
-            Can't be used to download or reuse the file.
-        width (:obj:`int`): Sticker width.
-        height (:obj:`int`): Sticker height.
-        is_animated (:obj:`bool`): :obj:`True`, if the sticker is animated.
-        thumb (:class:`telegram.PhotoSize`): Optional. Sticker thumbnail in the .webp or .jpg
-            format.
-        emoji (:obj:`str`): Optional. Emoji associated with the sticker.
-        set_name (:obj:`str`): Optional. Name of the sticker set to which the sticker belongs.
-        mask_position (:class:`telegram.MaskPosition`): Optional. For mask stickers, the position
-            where the mask should be placed.
-        file_size (:obj:`int`): Optional. File size.
-        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
-
     Args:
         file_id (:obj:`str`): Identifier for this file, which can be used to download
             or reuse the file.
@@ -68,22 +53,40 @@ class Sticker(TelegramObject):
         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.
+        file_unique_id (:obj:`str`): Unique identifier for this file, which
+            is supposed to be the same over time and for different bots.
+            Can't be used to download or reuse the file.
+        width (:obj:`int`): Sticker width.
+        height (:obj:`int`): Sticker height.
+        is_animated (:obj:`bool`): :obj:`True`, if the sticker is animated.
+        thumb (:class:`telegram.PhotoSize`): Optional. Sticker thumbnail in the .webp or .jpg
+            format.
+        emoji (:obj:`str`): Optional. Emoji associated with the sticker.
+        set_name (:obj:`str`): Optional. Name of the sticker set to which the sticker belongs.
+        mask_position (:class:`telegram.MaskPosition`): Optional. For mask stickers, the position
+            where the mask should be placed.
+        file_size (:obj:`int`): Optional. File size.
+        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
 
     """
 
-    def __init__(self,
-                 file_id: str,
-                 file_unique_id: str,
-                 width: int,
-                 height: int,
-                 is_animated: bool,
-                 thumb: PhotoSize = None,
-                 emoji: str = None,
-                 file_size: int = None,
-                 set_name: str = None,
-                 mask_position: 'MaskPosition' = None,
-                 bot: 'Bot' = None,
-                 **kwargs: Any):
+    def __init__(
+        self,
+        file_id: str,
+        file_unique_id: str,
+        width: int,
+        height: int,
+        is_animated: bool,
+        thumb: PhotoSize = None,
+        emoji: str = None,
+        file_size: int = None,
+        set_name: str = None,
+        mask_position: 'MaskPosition' = None,
+        bot: 'Bot' = None,
+        **_kwargs: Any,
+    ):
         # Required
         self.file_id = str(file_id)
         self.file_unique_id = str(file_unique_id)
@@ -112,24 +115,19 @@ class Sticker(TelegramObject):
 
         return cls(bot=bot, **data)
 
-    def get_file(self, timeout: str = None, api_kwargs: JSONDict = None) -> 'File':
+    def get_file(self, timeout: float = None, api_kwargs: JSONDict = None) -> 'File':
         """Convenience wrapper over :attr:`telegram.Bot.get_file`
 
-        Args:
-            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
-                the read timeout from the server (instead of the one specified during creation of
-                the connection pool).
-            api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the
-                Telegram API.
+        For the documentation of the arguments, please see :meth:`telegram.Bot.get_file`.
 
         Returns:
             :class:`telegram.File`
 
         Raises:
-            :class:`telegram.TelegramError`
+            :class:`telegram.error.TelegramError`
 
         """
-        return self.bot.get_file(self.file_id, timeout=timeout, api_kwargs=api_kwargs)
+        return self.bot.get_file(file_id=self.file_id, timeout=timeout, api_kwargs=api_kwargs)
 
 
 class StickerSet(TelegramObject):
@@ -158,15 +156,16 @@ class StickerSet(TelegramObject):
 
     """
 
-    def __init__(self,
-                 name: str,
-                 title: str,
-                 is_animated: bool,
-                 contains_masks: bool,
-                 stickers: List[Sticker],
-                 bot: 'Bot' = None,
-                 thumb: PhotoSize = None,
-                 **kwargs: Any):
+    def __init__(
+        self,
+        name: str,
+        title: str,
+        is_animated: bool,
+        contains_masks: bool,
+        stickers: List[Sticker],
+        thumb: PhotoSize = None,
+        **_kwargs: Any,
+    ):
         self.name = name
         self.title = title
         self.is_animated = is_animated
@@ -227,16 +226,17 @@ class MaskPosition(TelegramObject):
         scale (:obj:`float`): Mask scaling coefficient. For example, 2.0 means double size.
 
     """
-    FOREHEAD: str = 'forehead'
-    """:obj:`str`: 'forehead'"""
-    EYES: str = 'eyes'
-    """:obj:`str`: 'eyes'"""
-    MOUTH: str = 'mouth'
-    """:obj:`str`: 'mouth'"""
-    CHIN: str = 'chin'
-    """:obj:`str`: 'chin'"""
 
-    def __init__(self, point: str, x_shift: float, y_shift: float, scale: float, **kwargs: Any):
+    FOREHEAD: ClassVar[str] = constants.STICKER_FOREHEAD
+    """:const:`telegram.constants.STICKER_FOREHEAD`"""
+    EYES: ClassVar[str] = constants.STICKER_EYES
+    """:const:`telegram.constants.STICKER_EYES`"""
+    MOUTH: ClassVar[str] = constants.STICKER_MOUTH
+    """:const:`telegram.constants.STICKER_MOUTH`"""
+    CHIN: ClassVar[str] = constants.STICKER_CHIN
+    """:const:`telegram.constants.STICKER_CHIN`"""
+
+    def __init__(self, point: str, x_shift: float, y_shift: float, scale: float, **_kwargs: Any):
         self.point = point
         self.x_shift = x_shift
         self.y_shift = y_shift

telegram/files/venue.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -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 Venue."""
 
-from telegram import TelegramObject, Location
+from typing import TYPE_CHECKING, Any, Optional
+
+from telegram import Location, TelegramObject
 from telegram.utils.types import JSONDict
-from typing import Any, Optional, TYPE_CHECKING
+
 if TYPE_CHECKING:
     from telegram import Bot
 
@@ -31,13 +33,9 @@ class Venue(TelegramObject):
     Objects of this class are comparable in terms of equality. Two objects of this class are
     considered equal, if their :attr:`location` and :attr:`title` are equal.
 
-    Attributes:
-        location (:class:`telegram.Location`): Venue location.
-        title (:obj:`str`): Name of the venue.
-        address (:obj:`str`): Address of the venue.
-        foursquare_id (:obj:`str`): Optional. Foursquare identifier of the venue.
-        foursquare_type (:obj:`str`): Optional. Foursquare type of the venue. (For example,
-            "arts_entertainment/default", "arts_entertainment/aquarium" or "food/icecream".)
+    Note:
+      Foursquare details and Google Pace details are mutually exclusive. However, this
+      behaviour is undocumented and might be changed by Telegram.
 
     Args:
         location (:class:`telegram.Location`): Venue location.
@@ -46,17 +44,33 @@ class Venue(TelegramObject):
         foursquare_id (:obj:`str`, optional): Foursquare identifier of the venue.
         foursquare_type (:obj:`str`, optional): Foursquare type of the venue. (For example,
             "arts_entertainment/default", "arts_entertainment/aquarium" or "food/icecream".)
+        google_place_id (:obj:`str`, optional): Google Places identifier of the venue.
+        google_place_type (:obj:`str`, optional): Google Places type of the venue. (See
+            `supported types <https://developers.google.com/places/web-service/supported_types>`_.)
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
+    Attributes:
+        location (:class:`telegram.Location`): Venue location.
+        title (:obj:`str`): Name of the venue.
+        address (:obj:`str`): Address of the venue.
+        foursquare_id (:obj:`str`): Optional. Foursquare identifier of the venue.
+        foursquare_type (:obj:`str`): Optional. Foursquare type of the venue.
+        google_place_id (:obj:`str`): Optional. Google Places identifier of the venue.
+        google_place_type (:obj:`str`): Optional. Google Places type of the venue.
+
     """
 
-    def __init__(self,
-                 location: Location,
-                 title: str,
-                 address: str,
-                 foursquare_id: str = None,
-                 foursquare_type: str = None,
-                 **kwargs: Any):
+    def __init__(
+        self,
+        location: Location,
+        title: str,
+        address: str,
+        foursquare_id: str = None,
+        foursquare_type: str = None,
+        google_place_id: str = None,
+        google_place_type: str = None,
+        **_kwargs: Any,
+    ):
         # Required
         self.location = location
         self.title = title
@@ -64,6 +78,8 @@ class Venue(TelegramObject):
         # Optionals
         self.foursquare_id = foursquare_id
         self.foursquare_type = foursquare_type
+        self.google_place_id = google_place_id
+        self.google_place_type = google_place_type
 
         self._id_attrs = (self.location, self.title)
 

telegram/files/video.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -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 Video."""
 
+from typing import TYPE_CHECKING, Any, Optional
+
 from telegram import PhotoSize, TelegramObject
 from telegram.utils.types import JSONDict
-from typing import Any, Optional, TYPE_CHECKING
+
 if TYPE_CHECKING:
     from telegram import Bot, File
 
@@ -31,19 +33,6 @@ class Video(TelegramObject):
     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.
 
-    Attributes:
-        file_id (:obj:`str`): Identifier for this file.
-        file_unique_id (:obj:`str`): Unique identifier for this file, which
-            is supposed to be the same over time and for different bots.
-            Can't be used to download or reuse the file.
-        width (:obj:`int`): Video width as defined by sender.
-        height (:obj:`int`): Video height as defined by sender.
-        duration (:obj:`int`): Duration of the video in seconds as defined by sender.
-        thumb (:class:`telegram.PhotoSize`): Optional. Video thumbnail.
-        mime_type (:obj:`str`): Optional. Mime type of a file as defined by sender.
-        file_size (:obj:`int`): Optional. File size.
-        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
-
     Args:
         file_id (:obj:`str`): Identifier for this file, which can be used to download
             or reuse the file.
@@ -54,24 +43,42 @@ class Video(TelegramObject):
         height (:obj:`int`): Video height as defined by sender.
         duration (:obj:`int`): Duration of the video in seconds as defined by sender.
         thumb (:class:`telegram.PhotoSize`, optional): Video thumbnail.
+        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.
         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.
+        file_unique_id (:obj:`str`): Unique identifier for this file, which
+            is supposed to be the same over time and for different bots.
+            Can't be used to download or reuse the file.
+        width (:obj:`int`): Video width as defined by sender.
+        height (:obj:`int`): Video height as defined by sender.
+        duration (:obj:`int`): Duration of the video in seconds as defined by sender.
+        thumb (:class:`telegram.PhotoSize`): Optional. Video thumbnail.
+        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.
+        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
+
     """
 
-    def __init__(self,
-                 file_id: str,
-                 file_unique_id: str,
-                 width: int,
-                 height: int,
-                 duration: int,
-                 thumb: PhotoSize = None,
-                 mime_type: str = None,
-                 file_size: int = None,
-                 bot: 'Bot' = None,
-                 **kwargs: Any):
+    def __init__(
+        self,
+        file_id: str,
+        file_unique_id: str,
+        width: int,
+        height: int,
+        duration: int,
+        thumb: PhotoSize = None,
+        mime_type: str = None,
+        file_size: int = None,
+        bot: 'Bot' = None,
+        file_name: str = None,
+        **_kwargs: Any,
+    ):
         # Required
         self.file_id = str(file_id)
         self.file_unique_id = str(file_unique_id)
@@ -80,6 +87,7 @@ class Video(TelegramObject):
         self.duration = int(duration)
         # Optionals
         self.thumb = thumb
+        self.file_name = file_name
         self.mime_type = mime_type
         self.file_size = file_size
         self.bot = bot
@@ -97,21 +105,16 @@ class Video(TelegramObject):
 
         return cls(bot=bot, **data)
 
-    def get_file(self, timeout: int = None, api_kwargs: JSONDict = None) -> 'File':
+    def get_file(self, timeout: float = None, api_kwargs: JSONDict = None) -> 'File':
         """Convenience wrapper over :attr:`telegram.Bot.get_file`
 
-        Args:
-            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
-                the read timeout from the server (instead of the one specified during creation of
-                the connection pool).
-            api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the
-                Telegram API.
+        For the documentation of the arguments, please see :meth:`telegram.Bot.get_file`.
 
         Returns:
             :class:`telegram.File`
 
         Raises:
-            :class:`telegram.TelegramError`
+            :class:`telegram.error.TelegramError`
 
         """
-        return self.bot.get_file(self.file_id, timeout=timeout, api_kwargs=api_kwargs)
+        return self.bot.get_file(file_id=self.file_id, timeout=timeout, api_kwargs=api_kwargs)

telegram/files/videonote.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -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 VideoNote."""
 
+from typing import TYPE_CHECKING, Optional, Any
+
 from telegram import PhotoSize, TelegramObject
 from telegram.utils.types import JSONDict
-from typing import Any, Optional, TYPE_CHECKING
+
 if TYPE_CHECKING:
     from telegram import Bot, File
 
@@ -31,17 +33,6 @@ class VideoNote(TelegramObject):
     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.
 
-    Attributes:
-        file_id (:obj:`str`): Identifier for this file.
-        file_unique_id (:obj:`str`): Unique identifier for this file, which
-            is supposed to be the same over time and for different bots.
-            Can't be used to download or reuse the file.
-        length (:obj:`int`): Video width and height as defined by sender.
-        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.
-        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
-
     Args:
         file_id (:obj:`str`): Identifier for this file, which can be used to download
             or reuse the file.
@@ -56,17 +47,30 @@ class VideoNote(TelegramObject):
         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.
+        file_unique_id (:obj:`str`): Unique identifier for this file, which
+            is supposed to be the same over time and for different bots.
+            Can't be used to download or reuse the file.
+        length (:obj:`int`): Video width and height as defined by sender.
+        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.
+        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
+
     """
 
-    def __init__(self,
-                 file_id: str,
-                 file_unique_id: str,
-                 length: int,
-                 duration: int,
-                 thumb: PhotoSize = None,
-                 file_size: int = None,
-                 bot: 'Bot' = None,
-                 **kwargs: Any):
+    def __init__(
+        self,
+        file_id: str,
+        file_unique_id: str,
+        length: int,
+        duration: int,
+        thumb: PhotoSize = None,
+        file_size: int = None,
+        bot: 'Bot' = None,
+        **_kwargs: Any,
+    ):
         # Required
         self.file_id = str(file_id)
         self.file_unique_id = str(file_unique_id)
@@ -90,21 +94,16 @@ class VideoNote(TelegramObject):
 
         return cls(bot=bot, **data)
 
-    def get_file(self, timeout: int = None, api_kwargs: JSONDict = None) -> 'File':
+    def get_file(self, timeout: float = None, api_kwargs: JSONDict = None) -> 'File':
         """Convenience wrapper over :attr:`telegram.Bot.get_file`
 
-        Args:
-            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
-                the read timeout from the server (instead of the one specified during creation of
-                the connection pool).
-            api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the
-                Telegram API.
+        For the documentation of the arguments, please see :meth:`telegram.Bot.get_file`.
 
         Returns:
             :class:`telegram.File`
 
         Raises:
-            :class:`telegram.TelegramError`
+            :class:`telegram.error.TelegramError`
 
         """
-        return self.bot.get_file(self.file_id, timeout=timeout, api_kwargs=api_kwargs)
+        return self.bot.get_file(file_id=self.file_id, timeout=timeout, api_kwargs=api_kwargs)

telegram/files/voice.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015-2020
+# Copyright (C) 2015-2021
 # Leandro Toledo de Souza <devs@python-telegram-bot.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -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 Voice."""
 
+from typing import TYPE_CHECKING, Any
+
 from telegram import TelegramObject
 from telegram.utils.types import JSONDict
-from typing import Any, TYPE_CHECKING
+
 if TYPE_CHECKING:
     from telegram import Bot, File
 
@@ -31,16 +33,6 @@ class Voice(TelegramObject):
     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.
 
-    Attributes:
-        file_id (:obj:`str`): Identifier for this file.
-        file_unique_id (:obj:`str`): Unique identifier for this file, which
-            is supposed to be the same over time and for different bots.
-            Can't be used to download or reuse the file.
-        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.
-        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
-
     Args:
         file_id (:obj:`str`): Identifier for this file, which can be used to download
             or reuse the file.
@@ -53,16 +45,28 @@ class Voice(TelegramObject):
         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.
+        file_unique_id (:obj:`str`): Unique identifier for this file, which
+            is supposed to be the same over time and for different bots.
+            Can't be used to download or reuse the file.
+        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.
+        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
+
     """
 
-    def __init__(self,
-                 file_id: str,
-                 file_unique_id: str,
-                 duration: int,
-                 mime_type: str = None,
-                 file_size: int = None,
-                 bot: 'Bot' = None,
-                 **kwargs: Any):
+    def __init__(
+        self,
+        file_id: str,
+        file_unique_id: str,
+        duration: int,
+        mime_type: str = None,
+        file_size: int = None,
+        bot: 'Bot' = None,
+        **_kwargs: Any,
+    ):
         # Required
         self.file_id = str(file_id)
         self.file_unique_id = str(file_unique_id)
@@ -74,21 +78,16 @@ class Voice(TelegramObject):
 
         self._id_attrs = (self.file_unique_id,)
 
-    def get_file(self, timeout: int = None, api_kwargs: JSONDict = None) -> 'File':
+    def get_file(self, timeout: float = None, api_kwargs: JSONDict = None) -> 'File':
         """Convenience wrapper over :attr:`telegram.Bot.get_file`
 
-        Args:
-            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
-                the read timeout from the server (instead of the one specified during creation of
-                the connection pool).
-            api_kwargs (:obj:`dict`, optional): Arbitrary keyword arguments to be passed to the
-                Telegram API.
+        For the documentation of the arguments, please see :meth:`telegram.Bot.get_file`.
 
         Returns:
             :class:`telegram.File`
 
         Raises:
-            :class:`telegram.TelegramError`
+            :class:`telegram.error.TelegramError`
 
         """
-        return self.bot.get_file(self.file_id, timeout=timeout, api_kwargs=api_kwargs)
+        return self.bot.get_file(file_id=self.file_id, timeout=timeout, api_kwargs=api_kwargs)