Bump version to v12.7

* API 4.8

* Elaborate docs

* Address review

* Fix Message.to_json/dict() test

* More coverage

* Update telegram/bot.py

Co-authored-by: Noam Meltzer <tsnoam@gmail.com>

Co-authored-by: Noam Meltzer <tsnoam@gmail.com>

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Telegram Group
+    url: https://telegram.me/pythontelegrambotgroup
+    about: Questions asked on the group usually get answered faster.
+  - name: IRC Channel
+    url: https://webchat.freenode.net/?channels=##python-telegram-bot
+    about: In case you are unable to join our group due to Telegram restrictions, you can use our IRC channel

.github/ISSUE_TEMPLATE/question.md

@@ -10,7 +10,7 @@ assignees: ''
 <!--
 Hey there, you have a question? We are happy to answer. Please make sure no similar question was opened already.
 
-The following template is a suggestion how you can report an issue you run into whilst using our library. If you just want to ask a question, feel free to delete everything; just make sure you have a describing title :)
+To make it easier for us to help you, please try to follow the template below as closely as possible.
 
 Please mind that there is also a users' Telegram group at https://t.me/pythontelegrambotgroup for questions about the library. Questions asked there might be answered quicker than here. In case you are unable to join our group due to Telegram restrictions, you can use our IRC channel at https://webchat.freenode.net/?channels=##python-telegram-bot to participate in the group.
 -->

.github/workflows/test.yml

@@ -26,7 +26,7 @@ jobs:
             test-build: True
       fail-fast: False
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v2
       - name: Initialize vendored libs
         run:
           git submodule update --init --recursive
@@ -51,7 +51,7 @@ jobs:
           exit ${global_exit}
         env:
           JOB_INDEX: ${{ strategy.job-index }}
-          BOTS: W3sidG9rZW4iOiAiNjk2MTg4NzMyOkFBR1Z3RUtmSEhsTmpzY3hFRE5LQXdraEdzdFpfa28xbUMwIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6WldGaU1UUmxNbVF5TnpNeSIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gVHJhdmlzIHVzaW5nIENQeXRob24gMi43IiwgImJvdF91c2VybmFtZSI6ICJAcHRiX3RyYXZpc19jcHl0aG9uXzI3X2JvdCJ9LCB7InRva2VuIjogIjY3MTQ2ODg4NjpBQUdQR2ZjaVJJQlVORmU4MjR1SVZkcTdKZTNfWW5BVE5HdyIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOlpHWXdPVGxrTXpNeE4yWTIiLCAiYm90X25hbWUiOiAiUFRCIHRlc3RzIG9uIFRyYXZpcyB1c2luZyBDUHl0aG9uIDMuNCIsICJib3RfdXNlcm5hbWUiOiAiQHB0Yl90cmF2aXNfY3B5dGhvbl8zNF9ib3QifSwgeyJ0b2tlbiI6ICI2MjkzMjY1Mzg6QUFGUnJaSnJCN29CM211ekdzR0pYVXZHRTVDUXpNNUNVNG8iLCAicGF5bWVudF9wcm92aWRlcl90b2tlbiI6ICIyODQ2ODUwNjM6VEVTVDpNbU01WVdKaFl6a3hNMlUxIiwgImJvdF9uYW1lIjogIlBUQiB0ZXN0cyBvbiBUcmF2aXMgdXNpbmcgQ1B5dGhvbiAzLjUiLCAiYm90X3VzZXJuYW1lIjogIkBwdGJfdHJhdmlzX2NweXRob25fMzVfYm90In0sIHsidG9rZW4iOiAiNjQwMjA4OTQzOkFBRmhCalFwOXFtM1JUeFN6VXBZekJRakNsZS1Kano1aGNrIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6WXpoa1pUZzFOamMxWXpWbCIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gVHJhdmlzIHVzaW5nIENQeXRob24gMy42IiwgImJvdF91c2VybmFtZSI6ICJAcHRiX3RyYXZpc19jcHl0aG9uXzM2X2JvdCJ9LCB7InRva2VuIjogIjY5NTEwNDA4ODpBQUhmenlsSU9qU0lJUy1lT25JMjB5MkUyMEhvZEhzZnotMCIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOk9HUTFNRGd3WmpJd1pqRmwiLCAiYm90X25hbWUiOiAiUFRCIHRlc3RzIG9uIFRyYXZpcyB1c2luZyBDUHl0aG9uIDMuNyIsICJib3RfdXNlcm5hbWUiOiAiQHB0Yl90cmF2aXNfY3B5dGhvbl8zN19ib3QifSwgeyJ0b2tlbiI6ICI2OTE0MjM1NTQ6QUFGOFdrakNaYm5IcVBfaTZHaFRZaXJGRWxackdhWU9oWDAiLCAicGF5bWVudF9wcm92aWRlcl90b2tlbiI6ICIyODQ2ODUwNjM6VEVTVDpZamM1TlRoaU1tUXlNV1ZoIiwgImJvdF9uYW1lIjogIlBUQiB0ZXN0cyBvbiBUcmF2aXMgdXNpbmcgUHlQeSAyLjciLCAiYm90X3VzZXJuYW1lIjogIkBwdGJfdHJhdmlzX3B5cHlfMjdfYm90In0sIHsidG9rZW4iOiAiNjg0MzM5OTg0OkFBRk1nRUVqcDAxcjVyQjAwN3lDZFZOc2c4QWxOc2FVLWNjIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6TVRBek1UWTNNR1V5TmpnMCIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gVHJhdmlzIHVzaW5nIFB5UHkgMy41IiwgImJvdF91c2VybmFtZSI6ICJAcHRiX3RyYXZpc19weXB5XzM1X2JvdCJ9LCB7InRva2VuIjogIjY5MDA5MTM0NzpBQUZMbVI1cEFCNVljcGVfbU9oN3pNNEpGQk9oMHozVDBUbyIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOlpEaGxOekU1TURrd1lXSmkiLCAiYm90X25hbWUiOiAiUFRCIHRlc3RzIG9uIEFwcFZleW9yIHVzaW5nIENQeXRob24gMy40IiwgImJvdF91c2VybmFtZSI6ICJAcHRiX2FwcHZleW9yX2NweXRob25fMzRfYm90In0sIHsidG9rZW4iOiAiNjk0MzA4MDUyOkFBRUIyX3NvbkNrNTVMWTlCRzlBTy1IOGp4aVBTNTVvb0JBIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6WW1aaVlXWm1NakpoWkdNeSIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gQXBwVmV5b3IgdXNpbmcgQ1B5dGhvbiAyLjciLCAiYm90X3VzZXJuYW1lIjogIkBwdGJfYXBwdmV5b3JfY3B5dGhvbl8yN19ib3QifSwgeyJ0b2tlbiI6ICIxMDU1Mzk3NDcxOkFBRzE4bkJfUzJXQXd1SjNnN29oS0JWZ1hYY2VNbklPeVNjIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6TmpBd056QXpZalZpTkdOayIsICJuYW1lIjogIlBUQiB0ZXN0cyBbMF0iLCAidXNlcm5hbWUiOiAicHRiXzBfYm90In0sIHsidG9rZW4iOiAiMTA0NzMyNjc3MTpBQUY4bk90ODFGcFg4bGJidno4VWV3UVF2UmZUYkZmQnZ1SSIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOllUVTFOVEk0WkdSallqbGkiLCAibmFtZSI6ICJQVEIgdGVzdHMgWzFdIiwgInVzZXJuYW1lIjogInB0Yl8xX2JvdCJ9LCB7InRva2VuIjogIjk3MTk5Mjc0NTpBQUdPa09hVzBOSGpnSXY1LTlqUWJPajR2R3FkaFNGLVV1cyIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOk5XWmtNV1ZoWWpsallqVTUiLCAibmFtZSI6ICJQVEIgdGVzdHMgWzJdIiwgInVzZXJuYW1lIjogInB0Yl8yX2JvdCJ9XQ==
+          BOTS: W3sidG9rZW4iOiAiNjk2MTg4NzMyOkFBR1Z3RUtmSEhsTmpzY3hFRE5LQXdraEdzdFpfa28xbUMwIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6WldGaU1UUmxNbVF5TnpNeSIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gVHJhdmlzIHVzaW5nIENQeXRob24gMi43IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxMzkwOTgzOTk3IiwgImJvdF91c2VybmFtZSI6ICJAcHRiX3RyYXZpc19jcHl0aG9uXzI3X2JvdCJ9LCB7InRva2VuIjogIjY3MTQ2ODg4NjpBQUdQR2ZjaVJJQlVORmU4MjR1SVZkcTdKZTNfWW5BVE5HdyIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOlpHWXdPVGxrTXpNeE4yWTIiLCAiYm90X25hbWUiOiAiUFRCIHRlc3RzIG9uIFRyYXZpcyB1c2luZyBDUHl0aG9uIDMuNCIsICJzdXBlcl9ncm91cF9pZCI6ICItMTAwMTQ0NjAyMjUyMiIsICJib3RfdXNlcm5hbWUiOiAiQHB0Yl90cmF2aXNfY3B5dGhvbl8zNF9ib3QifSwgeyJ0b2tlbiI6ICI2MjkzMjY1Mzg6QUFGUnJaSnJCN29CM211ekdzR0pYVXZHRTVDUXpNNUNVNG8iLCAicGF5bWVudF9wcm92aWRlcl90b2tlbiI6ICIyODQ2ODUwNjM6VEVTVDpNbU01WVdKaFl6a3hNMlUxIiwgImJvdF9uYW1lIjogIlBUQiB0ZXN0cyBvbiBUcmF2aXMgdXNpbmcgQ1B5dGhvbiAzLjUiLCAic3VwZXJfZ3JvdXBfaWQiOiAiLTEwMDE0OTY5MTc3NTAiLCAiYm90X3VzZXJuYW1lIjogIkBwdGJfdHJhdmlzX2NweXRob25fMzVfYm90In0sIHsidG9rZW4iOiAiNjQwMjA4OTQzOkFBRmhCalFwOXFtM1JUeFN6VXBZekJRakNsZS1Kano1aGNrIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6WXpoa1pUZzFOamMxWXpWbCIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gVHJhdmlzIHVzaW5nIENQeXRob24gMy42IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxMzMzODcxNDYxIiwgImJvdF91c2VybmFtZSI6ICJAcHRiX3RyYXZpc19jcHl0aG9uXzM2X2JvdCJ9LCB7InRva2VuIjogIjY5NTEwNDA4ODpBQUhmenlsSU9qU0lJUy1lT25JMjB5MkUyMEhvZEhzZnotMCIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOk9HUTFNRGd3WmpJd1pqRmwiLCAiYm90X25hbWUiOiAiUFRCIHRlc3RzIG9uIFRyYXZpcyB1c2luZyBDUHl0aG9uIDMuNyIsICJzdXBlcl9ncm91cF9pZCI6ICItMTAwMTQ3ODI5MzcxNCIsICJib3RfdXNlcm5hbWUiOiAiQHB0Yl90cmF2aXNfY3B5dGhvbl8zN19ib3QifSwgeyJ0b2tlbiI6ICI2OTE0MjM1NTQ6QUFGOFdrakNaYm5IcVBfaTZHaFRZaXJGRWxackdhWU9oWDAiLCAicGF5bWVudF9wcm92aWRlcl90b2tlbiI6ICIyODQ2ODUwNjM6VEVTVDpZamM1TlRoaU1tUXlNV1ZoIiwgImJvdF9uYW1lIjogIlBUQiB0ZXN0cyBvbiBUcmF2aXMgdXNpbmcgUHlQeSAyLjciLCAic3VwZXJfZ3JvdXBfaWQiOiAiLTEwMDEzNjM5MzI1NzMiLCAiYm90X3VzZXJuYW1lIjogIkBwdGJfdHJhdmlzX3B5cHlfMjdfYm90In0sIHsidG9rZW4iOiAiNjg0MzM5OTg0OkFBRk1nRUVqcDAxcjVyQjAwN3lDZFZOc2c4QWxOc2FVLWNjIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6TVRBek1UWTNNR1V5TmpnMCIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gVHJhdmlzIHVzaW5nIFB5UHkgMy41IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxNDA3ODM2NjA1IiwgImJvdF91c2VybmFtZSI6ICJAcHRiX3RyYXZpc19weXB5XzM1X2JvdCJ9LCB7InRva2VuIjogIjY5MDA5MTM0NzpBQUZMbVI1cEFCNVljcGVfbU9oN3pNNEpGQk9oMHozVDBUbyIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOlpEaGxOekU1TURrd1lXSmkiLCAiYm90X25hbWUiOiAiUFRCIHRlc3RzIG9uIEFwcFZleW9yIHVzaW5nIENQeXRob24gMy40IiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxMjc5NjAwMDI2IiwgImJvdF91c2VybmFtZSI6ICJAcHRiX2FwcHZleW9yX2NweXRob25fMzRfYm90In0sIHsidG9rZW4iOiAiNjk0MzA4MDUyOkFBRUIyX3NvbkNrNTVMWTlCRzlBTy1IOGp4aVBTNTVvb0JBIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6WW1aaVlXWm1NakpoWkdNeSIsICJib3RfbmFtZSI6ICJQVEIgdGVzdHMgb24gQXBwVmV5b3IgdXNpbmcgQ1B5dGhvbiAyLjciLCAic3VwZXJfZ3JvdXBfaWQiOiAiLTEwMDEyOTMwNzkxNjUiLCAiYm90X3VzZXJuYW1lIjogIkBwdGJfYXBwdmV5b3JfY3B5dGhvbl8yN19ib3QifSwgeyJ0b2tlbiI6ICIxMDU1Mzk3NDcxOkFBRzE4bkJfUzJXQXd1SjNnN29oS0JWZ1hYY2VNbklPeVNjIiwgInBheW1lbnRfcHJvdmlkZXJfdG9rZW4iOiAiMjg0Njg1MDYzOlRFU1Q6TmpBd056QXpZalZpTkdOayIsICJuYW1lIjogIlBUQiB0ZXN0cyBbMF0iLCAic3VwZXJfZ3JvdXBfaWQiOiAiLTEwMDExODU1MDk2MzYiLCAidXNlcm5hbWUiOiAicHRiXzBfYm90In0sIHsidG9rZW4iOiAiMTA0NzMyNjc3MTpBQUY4bk90ODFGcFg4bGJidno4VWV3UVF2UmZUYkZmQnZ1SSIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOllUVTFOVEk0WkdSallqbGkiLCAibmFtZSI6ICJQVEIgdGVzdHMgWzFdIiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxNDg0Nzk3NjEyIiwgInVzZXJuYW1lIjogInB0Yl8xX2JvdCJ9LCB7InRva2VuIjogIjk3MTk5Mjc0NTpBQUdPa09hVzBOSGpnSXY1LTlqUWJPajR2R3FkaFNGLVV1cyIsICJwYXltZW50X3Byb3ZpZGVyX3Rva2VuIjogIjI4NDY4NTA2MzpURVNUOk5XWmtNV1ZoWWpsallqVTUiLCAibmFtZSI6ICJQVEIgdGVzdHMgWzJdIiwgInN1cGVyX2dyb3VwX2lkIjogIi0xMDAxNDAyMjU1MDcwIiwgInVzZXJuYW1lIjogInB0Yl8yX2JvdCJ9XQ==
           TEST_BUILD: ${{ matrix.test-build }}
           TEST_PRE_COMMIT: ${{ matrix.test-pre-commit }}
         shell: bash --noprofile --norc {0}
@@ -73,7 +73,7 @@ jobs:
         os: [ubuntu-latest]
       fail-fast: False
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v2
       - name: Initialize vendored libs
         run:
           git submodule update --init --recursive
@@ -102,7 +102,7 @@ jobs:
         os: [ubuntu-latest]
       fail-fast: False
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v2
       - name: Initialize vendored libs
         run:
           git submodule update --init --recursive

AUTHORS.rst

@@ -18,6 +18,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Alateas <https://github.com/alateas>`_
 - `Ales Dokshanin <https://github.com/alesdokshanin>`_
 - `Ambro17 <https://github.com/Ambro17>`_
+- `Andrej Zhilenkov <https://github.com/Andrej730>`_
 - `Anton Tagunov <https://github.com/anton-tagunov>`_
 - `Avanatiker <https://github.com/Avanatiker>`_
 - `Balduro <https://github.com/Balduro>`_
@@ -26,6 +27,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `d-qoi <https://github.com/d-qoi>`_
 - `daimajia <https://github.com/daimajia>`_
 - `Daniel Reed <https://github.com/nmlorg>`_
+- `D David Livingston <https://github.com/daviddl9>`_
 - `Eana Hufwe <https://github.com/blueset>`_
 - `Ehsan Online <https://github.com/ehsanonline>`_
 - `Eli Gao <https://github.com/eligao>`_
@@ -37,6 +39,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `evgfilim1 <https://github.com/evgfilim1>`_
 - `franciscod <https://github.com/franciscod>`_
 - `gamgi <https://github.com/gamgi>`_
+- `Harshil <https://github.com/harshil21>`_
 - `Hugo Damer <https://github.com/HakimusGIT>`_
 - `ihoru <https://github.com/ihoru>`_
 - `Jasmin Bom <https://github.com/jsmnbom>`_

CHANGES.rst

@@ -2,6 +2,96 @@
 Changelog
 =========
 
+Version 12.7
+============
+*Released 2020-05-02*
+
+**Major Changes:**
+
+- Bot API 4.8 support. **Note:** The ``Dice`` object now has a second positional argument ``emoji``. This is relevant, if you instantiate ``Dice`` objects manually. (`#1917`_)
+
+**New Features:**
+
+- New method ``run_mothly`` for the ``JobQueue`` (`#1705`_)
+- ``Job.next_t`` now gives the datetime of the jobs next execution (`#1685`_)
+
+**Minor changes, CI improvements, doc fixes or bug fixes:**
+
+- Added ``tzinfo`` argument to ``helpers.from_timestamp`` (`#1621`_)
+- Stabalize CI (`#1919`_, `#1931`_)
+- Use ABCs ``@abstractmethod`` instead of raising ``NotImplementedError`` for ``Handler``, ``BasePersistence`` and ``BaseFilter`` (`#1905`_)
+- Doc fixes (`#1914`_, `#1902`_, `#1910`_)
+
+.. _`#1902`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1902
+.. _`#1685`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1685
+.. _`#1910`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1910
+.. _`#1914`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1914
+.. _`#1931`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1931
+.. _`#1905`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1905
+.. _`#1919`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1919
+.. _`#1621`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1621
+.. _`#1705`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1705
+.. _`#1917`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1917
+
+Version 12.6.1
+==============
+*Released 2020-04-11*
+
+**Bug fixes:**
+
+- Fix serialization of ``reply_markup`` in media messages (`#1889`_)
+
+.. _`#1889`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1889
+
+Version 12.6
+============
+*Released 2020-04-10*
+
+**Major Changes:**
+
+- Bot API 4.7 support. **Note:** In ``Bot.create_new_sticker_set`` and ``Bot.add_sticker_to_set``, the order of the parameters had be changed, as the ``png_sticker`` parameter is now optional. (`#1858`_)
+
+**Minor changes, CI improvements or bug fixes:**
+
+- Add tests for ``swtich_inline_query(_current_chat)`` with empty string (`#1635`_)
+- Doc fixes (`#1854`_, `#1874`_, `#1884`_)
+- Update issue templates (`#1880`_)
+- Favor concrete types over "Iterable" (`#1882`_)
+- Pass last valid ``CallbackContext`` to ``TIMEOUT`` handlers of ``ConversationHandler`` (`#1826`_)
+- Tweak handling of persistence and update persistence after job calls (`#1827`_)
+- Use checkout@v2 for GitHub actions (`#1887`_)
+
+.. _`#1858`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1858
+.. _`#1635`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1635
+.. _`#1854`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1854
+.. _`#1874`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1874
+.. _`#1884`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1884
+.. _`#1880`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1880
+.. _`#1882`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1882
+.. _`#1826`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1826
+.. _`#1827`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1827
+.. _`#1887`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1887
+
+Version 12.5.1
+==============
+*Released 2020-03-30*
+
+**Minor changes, doc fixes or bug fixes:**
+
+- Add missing docs for `PollHandler` and `PollAnswerHandler` (`#1853`_)
+- Fix wording in `Filters` docs (`#1855`_)
+- Reorder tests to make them more stable (`#1835`_)
+- Make `ConversationHandler` attributes immutable (`#1756`_)
+- Make `PrefixHandler` attributes `command` and `prefix` editable (`#1636`_)
+- Fix UTC as default `tzinfo` for `Job` (`#1696`_)
+
+.. _`#1853`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1853
+.. _`#1855`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1855
+.. _`#1835`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1835
+.. _`#1756`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1756
+.. _`#1636`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1636
+.. _`#1696`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1696
+
 Version 12.5
 ============
 *Released 2020-03-29*

README.rst

@@ -93,7 +93,7 @@ make the development of bots easy and straightforward. These classes are contain
 Telegram API support
 ====================
 
-All types and methods of the Telegram Bot API **4.6** are supported.
+All types and methods of the Telegram Bot API **4.8** are supported.
 
 ==========
 Installing

docs/source/conf.py

@@ -58,9 +58,9 @@ author = u'Leandro Toledo'
 # built documents.
 #
 # The short X.Y version.
-version = '12.5'  # telegram.__version__[:3]
+version = '12.7'  # telegram.__version__[:3]
 # The full version, including alpha/beta/rc tags.
-release = '12.5'  # telegram.__version__
+release = '12.7'  # telegram.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/telegram.botcommand.rst

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

docs/source/telegram.dice.rst

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

docs/source/telegram.ext.pollanswerhandler.rst

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

docs/source/telegram.ext.pollhandler.rst

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

docs/source/telegram.ext.rst

@@ -26,6 +26,8 @@ Handlers
     telegram.ext.commandhandler
     telegram.ext.inlinequeryhandler
     telegram.ext.messagehandler
+    telegram.ext.pollanswerhandler
+    telegram.ext.pollhandler
     telegram.ext.precheckoutqueryhandler
     telegram.ext.prefixhandler
     telegram.ext.regexhandler

docs/source/telegram.rst

@@ -9,6 +9,7 @@ telegram package
     telegram.animation
     telegram.audio
     telegram.bot
+    telegram.botcommand
     telegram.callbackquery
     telegram.chat
     telegram.chataction
@@ -17,6 +18,7 @@ telegram package
     telegram.chatphoto
     telegram.constants
     telegram.contact
+    telegram.dice
     telegram.document
     telegram.error
     telegram.file

telegram/__init__.py

@@ -19,6 +19,7 @@
 """A library that provides a Python interface to the Telegram Bot API"""
 
 from .base import TelegramObject
+from .botcommand import BotCommand
 from .user import User
 from .files.chatphoto import ChatPhoto
 from .chat import Chat
@@ -36,6 +37,7 @@ from .files.location import Location
 from .files.venue import Venue
 from .files.videonote import VideoNote
 from .chataction import ChatAction
+from .dice import Dice
 from .userprofilephotos import UserProfilePhotos
 from .keyboardbutton import KeyboardButton
 from .keyboardbuttonpolltype import KeyboardButtonPollType
@@ -157,5 +159,6 @@ __all__ = [
     'InputMediaAudio', 'InputMediaDocument', 'TelegramDecryptionError',
     'PassportElementErrorSelfie', 'PassportElementErrorTranslationFile',
     'PassportElementErrorTranslationFiles', 'PassportElementErrorUnspecified', 'Poll',
-    'PollOption', 'PollAnswer', 'LoginUrl', 'KeyboardButton', 'KeyboardButtonPollType',
+    'PollOption', 'PollAnswer', 'LoginUrl', 'KeyboardButton', 'KeyboardButtonPollType', 'Dice',
+    'BotCommand'
 ]

telegram/base.py

@@ -23,13 +23,10 @@ try:
 except ImportError:
     import json
 
-from abc import ABCMeta
-
 
 class TelegramObject(object):
     """Base class for most telegram objects."""
 
-    __metaclass__ = ABCMeta
     _id_attrs = ()
 
     def __str__(self):

telegram/botcommand.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python
+# pylint: disable=R0903
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2020
+# 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 Telegram Bot Command."""
+from telegram import TelegramObject
+
+
+class BotCommand(TelegramObject):
+    """
+    This object represents a bot command.
+
+    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.
+    """
+    def __init__(self, command, description, **kwargs):
+        self.command = command
+        self.description = description
+
+    @classmethod
+    def de_json(cls, data, bot):
+        if not data:
+            return None
+
+        return cls(**data)

telegram/dice.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python
+# pylint: disable=R0903
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2020
+# 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 Telegram Dice."""
+from telegram import TelegramObject
+
+
+class Dice(TelegramObject):
+    """
+    This object represents a dice with random value from 1 to 6 for currently supported base eomji.
+    (The singular form of "dice" is "die". However, PTB mimics the Telegram API, which uses the
+    term "dice".)
+
+    Note:
+        If :attr:`emoji` is "🎯", a value of 6 currently represents a bullseye, while a value of 1
+        indicates that the dartboard was missed. However, this behaviour is undocumented and might
+        be changed by Telegram.
+
+    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.
+        emoji (:obj:`str`): Emoji on which the dice throw animation is based.
+    """
+    def __init__(self, value, emoji, **kwargs):
+        self.value = value
+        self.emoji = emoji
+
+    @classmethod
+    def de_json(cls, data, bot):
+        if not data:
+            return None
+
+        return cls(**data)
+
+    DICE = '🎲'
+    """:obj:`str`: '🎲'"""
+    DARTS = '🎯'
+    """:obj:`str`: '🎯'"""
+    ALL_EMOJI = [DICE, DARTS]
+    """List[:obj:`str`]: List of all supported base emoji. Currently :attr:`DICE` and
+    :attr:`DARTS`."""

telegram/ext/basepersistence.py

@@ -18,8 +18,10 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the BasePersistence class."""
 
+from abc import ABC, abstractmethod
 
-class BasePersistence(object):
+
+class BasePersistence(ABC):
     """Interface class for adding persistence to your bot.
     Subclass this object for different implementations of a persistent bot.
 
@@ -57,6 +59,7 @@ class BasePersistence(object):
         self.store_chat_data = store_chat_data
         self.store_bot_data = store_bot_data
 
+    @abstractmethod
     def get_user_data(self):
         """"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
@@ -65,8 +68,8 @@ class BasePersistence(object):
         Returns:
             :obj:`defaultdict`: The restored user data.
         """
-        raise NotImplementedError
 
+    @abstractmethod
     def get_chat_data(self):
         """"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
@@ -75,8 +78,8 @@ class BasePersistence(object):
         Returns:
             :obj:`defaultdict`: The restored chat data.
         """
-        raise NotImplementedError
 
+    @abstractmethod
     def get_bot_data(self):
         """"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
@@ -85,8 +88,8 @@ class BasePersistence(object):
         Returns:
             :obj:`defaultdict`: The restored bot data.
         """
-        raise NotImplementedError
 
+    @abstractmethod
     def get_conversations(self, name):
         """"Will be called by :class:`telegram.ext.Dispatcher` when a
         :class:`telegram.ext.ConversationHandler` is added if
@@ -99,8 +102,8 @@ class BasePersistence(object):
         Returns:
             :obj:`dict`: The restored conversations for the handler.
         """
-        raise NotImplementedError
 
+    @abstractmethod
     def update_conversation(self, name, key, new_state):
         """Will be called when a :attr:`telegram.ext.ConversationHandler.update_state`
         is called. this allows the storeage of the new state in the persistence.
@@ -110,8 +113,8 @@ class BasePersistence(object):
             key (:obj:`tuple`): The key the state is changed for.
             new_state (:obj:`tuple` | :obj:`any`): The new state for the given key.
         """
-        raise NotImplementedError
 
+    @abstractmethod
     def update_user_data(self, user_id, data):
         """Will be called by the :class:`telegram.ext.Dispatcher` after a handler has
         handled an update.
@@ -120,8 +123,8 @@ class BasePersistence(object):
             user_id (:obj:`int`): The user the data might have been changed for.
             data (:obj:`dict`): The :attr:`telegram.ext.dispatcher.user_data` [user_id].
         """
-        raise NotImplementedError
 
+    @abstractmethod
     def update_chat_data(self, chat_id, data):
         """Will be called by the :class:`telegram.ext.Dispatcher` after a handler has
         handled an update.
@@ -130,8 +133,8 @@ class BasePersistence(object):
             chat_id (:obj:`int`): The chat the data might have been changed for.
             data (:obj:`dict`): The :attr:`telegram.ext.dispatcher.chat_data` [chat_id].
         """
-        raise NotImplementedError
 
+    @abstractmethod
     def update_bot_data(self, data):
         """Will be called by the :class:`telegram.ext.Dispatcher` after a handler has
         handled an update.
@@ -139,7 +142,6 @@ class BasePersistence(object):
         Args:
             data (:obj:`dict`): The :attr:`telegram.ext.dispatcher.bot_data` .
         """
-        raise NotImplementedError
 
     def flush(self):
         """Will be called by :class:`telegram.ext.Updater` upon receiving a stop signal. Gives the

telegram/ext/commandhandler.py

@@ -302,6 +302,10 @@ class PrefixHandler(CommandHandler):
                  pass_user_data=False,
                  pass_chat_data=False):
 
+        self._prefix = list()
+        self._command = list()
+        self._commands = list()
+
         super(PrefixHandler, self).__init__(
             'nocommand', callback, filters=filters, allow_edited=None, pass_args=pass_args,
             pass_update_queue=pass_update_queue,
@@ -309,15 +313,36 @@ class PrefixHandler(CommandHandler):
             pass_user_data=pass_user_data,
             pass_chat_data=pass_chat_data)
 
+        self.prefix = prefix
+        self.command = command
+        self._build_commands()
+
+    @property
+    def prefix(self):
+        return self._prefix
+
+    @prefix.setter
+    def prefix(self, prefix):
         if isinstance(prefix, string_types):
-            self.prefix = [prefix.lower()]
+            self._prefix = [prefix.lower()]
         else:
-            self.prefix = prefix
+            self._prefix = prefix
+        self._build_commands()
+
+    @property
+    def command(self):
+        return self._command
+
+    @command.setter
+    def command(self, command):
         if isinstance(command, string_types):
-            self.command = [command.lower()]
+            self._command = [command.lower()]
         else:
-            self.command = command
-        self.command = [x.lower() + y.lower() for x in self.prefix for y in self.command]
+            self._command = command
+        self._build_commands()
+
+    def _build_commands(self):
+        self._commands = [x.lower() + y.lower() for x in self.prefix for y in self.command]
 
     def check_update(self, update):
         """Determines whether an update should be passed to this handlers :attr:`callback`.
@@ -334,7 +359,7 @@ class PrefixHandler(CommandHandler):
 
             if message.text:
                 text_list = message.text.split()
-                if text_list[0].lower() not in self.command:
+                if text_list[0].lower() not in self._commands:
                     return None
                 filter_result = self.filters(update)
                 if filter_result:

telegram/ext/conversationhandler.py

@@ -29,10 +29,11 @@ from telegram.utils.promise import Promise
 
 
 class _ConversationTimeoutContext(object):
-    def __init__(self, conversation_key, update, dispatcher):
+    def __init__(self, conversation_key, update, dispatcher, callback_context):
         self.conversation_key = conversation_key
         self.update = update
         self.dispatcher = dispatcher
+        self.callback_context = callback_context
 
 
 class ConversationHandler(Handler):
@@ -96,8 +97,9 @@ class ConversationHandler(Handler):
         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 will be handled by ALL the handler's who's `check_update` method
-            returns True that are in the state :attr:`ConversationHandler.TIMEOUT`.
+            last received update and the corresponding ``context`` will be handled by ALL the
+            handler's who's `check_update` method returns 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
@@ -130,8 +132,9 @@ class ConversationHandler(Handler):
         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 or None (default), there will be no timeout. The last
-            received update will be handled by ALL the handler's who's `check_update` method
-            returns True that are in the state :attr:`ConversationHandler.TIMEOUT`.
+            received update and the corresponding ``context`` will be handled by ALL the handler's
+            who's `check_update` method returns 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
@@ -165,23 +168,23 @@ class ConversationHandler(Handler):
                  persistent=False,
                  map_to_parent=None):
 
-        self.entry_points = entry_points
-        self.states = states
-        self.fallbacks = fallbacks
+        self._entry_points = entry_points
+        self._states = states
+        self._fallbacks = fallbacks
 
-        self.allow_reentry = allow_reentry
-        self.per_user = per_user
-        self.per_chat = per_chat
-        self.per_message = per_message
-        self.conversation_timeout = conversation_timeout
-        self.name = name
+        self._allow_reentry = allow_reentry
+        self._per_user = per_user
+        self._per_chat = per_chat
+        self._per_message = per_message
+        self._conversation_timeout = conversation_timeout
+        self._name = name
         if persistent and not self.name:
             raise ValueError("Conversations can't be persistent when handler is unnamed.")
         self.persistent = persistent
         self._persistence = None
         """:obj:`telegram.ext.BasePersistance`: The persistence used to store conversations.
         Set by dispatcher"""
-        self.map_to_parent = map_to_parent
+        self._map_to_parent = map_to_parent
 
         self.timeout_jobs = dict()
         self._timeout_jobs_lock = Lock()
@@ -225,6 +228,87 @@ class ConversationHandler(Handler):
                                   "since inline queries have no chat context.")
                     break
 
+    @property
+    def entry_points(self):
+        return self._entry_points
+
+    @entry_points.setter
+    def entry_points(self, value):
+        raise ValueError('You can not assign a new value to entry_points after initialization.')
+
+    @property
+    def states(self):
+        return self._states
+
+    @states.setter
+    def states(self, value):
+        raise ValueError('You can not assign a new value to states after initialization.')
+
+    @property
+    def fallbacks(self):
+        return self._fallbacks
+
+    @fallbacks.setter
+    def fallbacks(self, value):
+        raise ValueError('You can not assign a new value to fallbacks after initialization.')
+
+    @property
+    def allow_reentry(self):
+        return self._allow_reentry
+
+    @allow_reentry.setter
+    def allow_reentry(self, value):
+        raise ValueError('You can not assign a new value to allow_reentry after initialization.')
+
+    @property
+    def per_user(self):
+        return self._per_user
+
+    @per_user.setter
+    def per_user(self, value):
+        raise ValueError('You can not assign a new value to per_user after initialization.')
+
+    @property
+    def per_chat(self):
+        return self._per_chat
+
+    @per_chat.setter
+    def per_chat(self, value):
+        raise ValueError('You can not assign a new value to per_chat after initialization.')
+
+    @property
+    def per_message(self):
+        return self._per_message
+
+    @per_message.setter
+    def per_message(self, value):
+        raise ValueError('You can not assign a new value to per_message after initialization.')
+
+    @property
+    def conversation_timeout(self):
+        return self._conversation_timeout
+
+    @conversation_timeout.setter
+    def conversation_timeout(self, value):
+        raise ValueError('You can not assign a new value to conversation_timeout after '
+                         'initialization.')
+
+    @property
+    def name(self):
+        return self._name
+
+    @name.setter
+    def name(self, value):
+        raise ValueError('You can not assign a new value to name after initialization.')
+
+    @property
+    def map_to_parent(self):
+        return self._map_to_parent
+
+    @map_to_parent.setter
+    def map_to_parent(self, value):
+        raise ValueError('You can not assign a new value to map_to_parent after initialization.')
+
     @property
     def persistence(self):
         return self._persistence
@@ -385,7 +469,8 @@ class ConversationHandler(Handler):
                 # Add the new timeout job
                 self.timeout_jobs[conversation_key] = dispatcher.job_queue.run_once(
                     self._trigger_timeout, self.conversation_timeout,
-                    context=_ConversationTimeoutContext(conversation_key, update, dispatcher))
+                    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)
@@ -422,9 +507,9 @@ class ConversationHandler(Handler):
         callback_context = None
         if isinstance(context, CallbackContext):
             job = context.job
-            callback_context = context
 
         context = job.context
+        callback_context = context.callback_context
 
         with self._timeout_jobs_lock:
             found_job = self.timeout_jobs[context.conversation_key]

telegram/ext/dictpersistence.py

@@ -226,6 +226,8 @@ class DictPersistence(BasePersistence):
             user_id (:obj:`int`): The user the data might have been changed for.
             data (:obj:`dict`): The :attr:`telegram.ext.dispatcher.user_data` [user_id].
         """
+        if self._user_data is None:
+            self._user_data = defaultdict(dict)
         if self._user_data.get(user_id) == data:
             return
         self._user_data[user_id] = data
@@ -238,6 +240,8 @@ class DictPersistence(BasePersistence):
             chat_id (:obj:`int`): The chat the data might have been changed for.
             data (:obj:`dict`): The :attr:`telegram.ext.dispatcher.chat_data` [chat_id].
         """
+        if self._chat_data is None:
+            self._chat_data = defaultdict(dict)
         if self._chat_data.get(chat_id) == data:
             return
         self._chat_data[chat_id] = data

telegram/ext/dispatcher.py

@@ -323,53 +323,6 @@ class Dispatcher(object):
 
         """
 
-        def persist_update(update):
-            """Persist a single update.
-
-            Args:
-            update (:class:`telegram.Update`):
-                The update to process.
-
-            """
-            if self.persistence and isinstance(update, Update):
-                if self.persistence.store_bot_data:
-                    try:
-                        self.persistence.update_bot_data(self.bot_data)
-                    except Exception as e:
-                        try:
-                            self.dispatch_error(update, e)
-                        except Exception:
-                            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 and update.effective_chat:
-                    chat_id = update.effective_chat.id
-                    try:
-                        self.persistence.update_chat_data(chat_id,
-                                                          self.chat_data[chat_id])
-                    except Exception as e:
-                        try:
-                            self.dispatch_error(update, e)
-                        except Exception:
-                            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 and update.effective_user:
-                    user_id = update.effective_user.id
-                    try:
-                        self.persistence.update_user_data(user_id,
-                                                          self.user_data[user_id])
-                    except Exception as e:
-                        try:
-                            self.dispatch_error(update, e)
-                        except Exception:
-                            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)
-
         # An error happened while polling
         if isinstance(update, TelegramError):
             try:
@@ -388,13 +341,13 @@ class Dispatcher(object):
                         if not context and self.use_context:
                             context = CallbackContext.from_update(update, self)
                         handler.handle_update(update, self, check, context)
-                        persist_update(update)
+                        self.update_persistence(update=update)
                         break
 
             # Stop processing with any other handler.
             except DispatcherHandlerStop:
                 self.logger.debug('Stopping further handlers due to DispatcherHandlerStop')
-                persist_update(update)
+                self.update_persistence(update=update)
                 break
 
             # Dispatch any error.
@@ -471,18 +424,62 @@ class Dispatcher(object):
                 del self.handlers[group]
                 self.groups.remove(group)
 
-    def update_persistence(self):
+    def update_persistence(self, update=None):
         """Update :attr:`user_data`, :attr:`chat_data` and :attr:`bot_data` in :attr:`persistence`.
+
+        Args:
+            update (:class:`telegram.Update`, optional): The update to process. If passed, only the
+            corresponding ``user_data`` and ``chat_data`` will be updated.
         """
         if self.persistence:
+            chat_ids = self.chat_data.keys()
+            user_ids = self.user_data.keys()
+
+            if isinstance(update, Update):
+                if update.effective_chat:
+                    chat_ids = [update.effective_chat.id]
+                else:
+                    chat_ids = []
+                if update.effective_user:
+                    user_ids = [update.effective_user.id]
+                else:
+                    user_ids = []
+
             if self.persistence.store_bot_data:
-                self.persistence.update_bot_data(self.bot_data)
+                try:
+                    self.persistence.update_bot_data(self.bot_data)
+                except Exception as e:
+                    try:
+                        self.dispatch_error(update, e)
+                    except Exception:
+                        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 self.chat_data:
-                    self.persistence.update_chat_data(chat_id, self.chat_data[chat_id])
+                for chat_id in chat_ids:
+                    try:
+                        self.persistence.update_chat_data(chat_id, self.chat_data[chat_id])
+                    except Exception as e:
+                        try:
+                            self.dispatch_error(update, e)
+                        except Exception:
+                            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 self.user_data:
-                    self.persistence.update_user_data(user_id, self.user_data[user_id])
+                for user_id in user_ids:
+                    try:
+                        self.persistence.update_user_data(user_id, self.user_data[user_id])
+                    except Exception as e:
+                        try:
+                            self.dispatch_error(update, e)
+                        except Exception:
+                            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):
         """Registers an error handler in the Dispatcher. This handler will receive every error

telegram/ext/filters.py

@@ -21,13 +21,14 @@
 import re
 
 from future.utils import string_types
+from abc import ABC, abstractmethod
 
 from telegram import Chat, Update, MessageEntity
 
 __all__ = ['Filters', 'BaseFilter', 'InvertedFilter', 'MergedFilter']
 
 
-class BaseFilter(object):
+class BaseFilter(ABC):
     """Base class for all Message Filters.
 
     Subclassing from this class filters to be combined using bitwise operators:
@@ -50,7 +51,7 @@ class BaseFilter(object):
         >>> Filters.text & (~ Filters.forwarded)
 
     Note:
-        Filters use the same short circuiting logic that pythons `and`, `or` and `not`.
+        Filters use the same short circuiting logic as python's `and`, `or` and `not`.
         This means that for example:
 
             >>> Filters.regex(r'(a?x)') | Filters.regex(r'(b?x)')
@@ -103,6 +104,7 @@ class BaseFilter(object):
             self.name = self.__class__.__name__
         return self.name
 
+    @abstractmethod
     def filter(self, update):
         """This method must be overwritten.
 
@@ -118,8 +120,6 @@ class BaseFilter(object):
 
         """
 
-        raise NotImplementedError
-
 
 class InvertedFilter(BaseFilter):
     """Represents a filter that has been inverted.
@@ -215,6 +215,38 @@ class MergedFilter(BaseFilter):
                                    self.and_filter or self.or_filter)
 
 
+class _DiceEmoji(BaseFilter):
+
+    def __init__(self, emoji=None, name=None):
+        self.name = 'Filters.dice.{}'.format(name) if name else 'Filters.dice'
+        self.emoji = emoji
+
+    class _DiceValues(BaseFilter):
+
+        def __init__(self, values, name, emoji=None):
+            self.values = [values] if isinstance(values, int) else values
+            self.emoji = emoji
+            self.name = '{}({})'.format(name, values)
+
+        def filter(self, message):
+            if bool(message.dice and message.dice.value in self.values):
+                if self.emoji:
+                    return message.dice.emoji == self.emoji
+                return True
+
+    def __call__(self, update):
+        if isinstance(update, Update):
+            return self.filter(update.effective_message)
+        else:
+            return self._DiceValues(update, self.name, emoji=self.emoji)
+
+    def filter(self, message):
+        if bool(message.dice):
+            if self.emoji:
+                return message.dice.emoji == self.emoji
+            return True
+
+
 class Filters(object):
     """Predefined filters for use as the `filter` argument of :class:`telegram.ext.MessageHandler`.
 
@@ -236,35 +268,35 @@ class Filters(object):
     class _Text(BaseFilter):
         name = 'Filters.text'
 
-        class _TextIterable(BaseFilter):
+        class _TextStrings(BaseFilter):
 
-            def __init__(self, iterable):
-                self.iterable = iterable
-                self.name = 'Filters.text({})'.format(iterable)
+            def __init__(self, strings):
+                self.strings = strings
+                self.name = 'Filters.text({})'.format(strings)
 
             def filter(self, message):
                 if message.text:
-                    return message.text in self.iterable
+                    return message.text in self.strings
                 return False
 
         def __call__(self, update):
             if isinstance(update, Update):
                 return self.filter(update.effective_message)
             else:
-                return self._TextIterable(update)
+                return self._TextStrings(update)
 
         def filter(self, message):
             return bool(message.text)
 
     text = _Text()
-    """Text Messages. If an iterable of strings is passed, it filters messages to only allow those
-    whose text is appearing in the given iterable.
+    """Text Messages. If a list of strings is passed, it filters messages to only allow those
+    whose text is appearing in the given list.
 
     Examples:
         To allow any text message, simply use
         ``MessageHandler(Filters.text, callback_method)``.
 
-        A simple usecase for passing an iterable is to allow only messages that were send by a
+        A simple usecase for passing a list is to allow only messages that were send by a
         custom :class:`telegram.ReplyKeyboardMarkup`::
 
             buttons = ['Start', 'Settings', 'Back']
@@ -272,44 +304,51 @@ class Filters(object):
             ...
             MessageHandler(Filters.text(buttons), callback_method)
 
+    Note:
+        * Dice messages don't have text. If you want to filter either text or dice messages, use
+          ``Filters.text | Filters.dice``.
+        * Messages containing a command are accepted by this filter. Use
+          ``Filters.text & (~Filters.command)``, if you want to filter only text messages without
+          commands.
+
     Args:
-        update (Iterable[:obj:`str`], optional): Which messages to allow. Only exact matches
-            are allowed. If not specified, will allow any text message.
+        update (List[:obj:`str`] | Tuple[:obj:`str`], optional): Which messages to allow. Only
+            exact matches are allowed. If not specified, will allow any text message.
     """
 
     class _Caption(BaseFilter):
         name = 'Filters.caption'
 
-        class _CaptionIterable(BaseFilter):
+        class _CaptionStrings(BaseFilter):
 
-            def __init__(self, iterable):
-                self.iterable = iterable
-                self.name = 'Filters.caption({})'.format(iterable)
+            def __init__(self, strings):
+                self.strings = strings
+                self.name = 'Filters.caption({})'.format(strings)
 
             def filter(self, message):
                 if message.caption:
-                    return message.caption in self.iterable
+                    return message.caption in self.strings
                 return False
 
         def __call__(self, update):
             if isinstance(update, Update):
                 return self.filter(update.effective_message)
             else:
-                return self._CaptionIterable(update)
+                return self._CaptionStrings(update)
 
         def filter(self, message):
             return bool(message.caption)
 
     caption = _Caption()
-    """Messages with a caption. If an iterable of strings is passed, it filters messages to only
-    allow those whose caption is appearing in the given iterable.
+    """Messages with a caption. If a list of strings is passed, it filters messages to only
+    allow those whose caption is appearing in the given list.
 
     Examples:
         ``MessageHandler(Filters.caption, callback_method)``
 
     Args:
-        update (Iterable[:obj:`str`], optional): Which captions to allow. Only exact matches
-            are allowed. If not specified, will allow any message with a caption.
+        update (List[:obj:`str`] | Tuple[:obj:`str`], optional): Which captions to allow. Only
+            exact matches are allowed. If not specified, will allow any message with a caption.
     """
 
     class _Command(BaseFilter):
@@ -346,6 +385,9 @@ class Filters(object):
         MessageHandler(Filters.command, command_at_start_callback)
         MessageHandler(Filters.command(False), command_anywhere_callback)
 
+    Note:
+        ``Filters.text`` also accepts messages containing a command.
+
     Args:
         update (:obj:`bool`, optional): Whether to only allow messages that `start` with a bot
             command. Defaults to ``True``.
@@ -368,7 +410,7 @@ class Filters(object):
             if you need to specify flags on your pattern.
 
         Note:
-            Filters use the same short circuiting logic that pythons `and`, `or` and `not`.
+            Filters use the same short circuiting logic as python's `and`, `or` and `not`.
             This means that for example:
 
                 >>> Filters.regex(r'(a?x)') | Filters.regex(r'(b?x)')
@@ -427,7 +469,7 @@ class Filters(object):
                     send media with wrong types that don't fit to this handler.
 
             Example:
-                Filters.documents.category('audio/') returnes `True` for all types
+                Filters.documents.category('audio/') returns `True` for all types
                 of audio sent as file, for example 'audio/mpeg' or 'audio/x-wav'
             """
 
@@ -957,6 +999,37 @@ officedocument.wordprocessingml.document")``-
     poll = _Poll()
     """Messages that contain a :class:`telegram.Poll`."""
 
+    class _Dice(_DiceEmoji):
+        dice = _DiceEmoji('🎲', 'dice')
+        darts = _DiceEmoji('🎯', 'darts')
+
+    dice = _Dice()
+    """Dice Messages. If an integer or a list of integers is passed, it filters messages to only
+    allow those whose dice value is appearing in the given list.
+
+    Examples:
+        To allow any dice message, simply use
+        ``MessageHandler(Filters.dice, callback_method)``.
+        To allow only dice with value 6, use
+        ``MessageHandler(Filters.dice(6), callback_method)``.
+        To allow only dice with value 5 `or` 6, use
+        ``MessageHandler(Filters.dice([5, 6]), callback_method)``.
+
+    Args:
+        update (:obj:`int` | List[:obj:`int`], optional): Which values to allow. If not
+            specified, will allow any dice message.
+
+    Note:
+        Dice messages don't have text. If you want to filter either text or dice messages, use
+        ``Filters.text | Filters.dice``.
+
+    Attributes:
+        dice: Dice messages with the emoji 🎲. Passing a list of integers is supported just as for
+            :attr:`Filters.dice`.
+        darts: Dice messages with the emoji 🎯. Passing a list of integers is supported just as for
+            :attr:`Filters.dice`.
+    """
+
     class language(BaseFilter):
         """Filters messages to only allow those which are from users with a certain language code.
 

telegram/ext/handler.py

@@ -18,8 +18,10 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the base class for handlers as used by the Dispatcher."""
 
+from abc import ABC, abstractmethod
 
-class Handler(object):
+
+class Handler(ABC):
     """The base class for all update handlers. Create custom handlers by inheriting from it.
 
     Attributes:
@@ -82,6 +84,7 @@ class Handler(object):
         self.pass_user_data = pass_user_data
         self.pass_chat_data = pass_chat_data
 
+    @abstractmethod
     def check_update(self, update):
         """
         This method is called to determine if an update should be handled by
@@ -96,7 +99,6 @@ class Handler(object):
             when the update gets handled.
 
         """
-        raise NotImplementedError
 
     def handle_update(self, update, dispatcher, check_result, context=None):
         """

telegram/ext/jobqueue.py

@@ -18,6 +18,7 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes JobQueue and Job."""
 
+import calendar
 import datetime
 import logging
 import time
@@ -29,7 +30,7 @@ from threading import Thread, Lock, Event
 
 from telegram.ext.callbackcontext import CallbackContext
 from telegram.utils.deprecate import TelegramDeprecationWarning
-from telegram.utils.helpers import to_float_timestamp, _UTC
+from telegram.utils.helpers import to_float_timestamp
 
 
 class Days(object):
@@ -104,6 +105,7 @@ class JobQueue(object):
         # enqueue:
         self.logger.debug('Putting job %s with t=%s', job.name, time_spec)
         self._queue.put((next_t, job))
+        job._set_next_t(next_t)
 
         # Wake up the loop if this job should be executed next
         self._set_next_peek(next_t)
@@ -129,10 +131,14 @@ class JobQueue(object):
                 * :obj:`datetime.timedelta` will be interpreted as "time from now" in which the
                   job should run.
                 * :obj:`datetime.datetime` will be interpreted as a specific date and time at
-                  which the job should run.
+                  which the job should run. If the timezone (``datetime.tzinfo``) is ``None``, UTC
+                  will be assumed.
                 * :obj:`datetime.time` will be interpreted as a specific time of day at which the
                   job should run. This could be either today or, if the time has already passed,
-                  tomorrow.
+                  tomorrow. If the timezone (``time.tzinfo``) is ``None``, UTC will be assumed.
+
+                If ``when`` is :obj:`datetime.datetime` or :obj:`datetime.time` type
+                then ``when.tzinfo`` will define ``Job.tzinfo``. Otherwise UTC will be assumed.
 
             context (:obj:`object`, optional): Additional data needed for the callback function.
                 Can be accessed through ``job.context`` in the callback. Defaults to ``None``.
@@ -144,7 +150,14 @@ class JobQueue(object):
             queue.
 
         """
-        job = Job(callback, repeat=False, context=context, name=name, job_queue=self)
+        tzinfo = when.tzinfo if isinstance(when, (datetime.datetime, datetime.time)) else None
+
+        job = Job(callback,
+                  repeat=False,
+                  context=context,
+                  name=name,
+                  job_queue=self,
+                  tzinfo=tzinfo)
         self._put(job, time_spec=when)
         return job
 
@@ -172,10 +185,14 @@ class JobQueue(object):
                 * :obj:`datetime.timedelta` will be interpreted as "time from now" in which the
                   job should run.
                 * :obj:`datetime.datetime` will be interpreted as a specific date and time at
-                  which the job should run.
+                  which the job should run. If the timezone (``datetime.tzinfo``) is ``None``, UTC
+                  will be assumed.
                 * :obj:`datetime.time` will be interpreted as a specific time of day at which the
                   job should run. This could be either today or, if the time has already passed,
-                  tomorrow.
+                  tomorrow. If the timezone (``time.tzinfo``) is ``None``, UTC will be assumed.
+
+                If ``first`` is :obj:`datetime.datetime` or :obj:`datetime.time` type
+                then ``first.tzinfo`` will define ``Job.tzinfo``. Otherwise UTC will be assumed.
 
                 Defaults to ``interval``
             context (:obj:`object`, optional): Additional data needed for the callback function.
@@ -187,21 +204,131 @@ class JobQueue(object):
             :class:`telegram.ext.Job`: The new ``Job`` instance that has been added to the job
             queue.
 
-        Notes:
+        Note:
              `interval` is always respected "as-is". That means that if DST changes during that
              interval, the job might not run at the time one would expect. It is always recommended
              to pin servers to UTC time, then time related behaviour can always be expected.
 
         """
+        tzinfo = first.tzinfo if isinstance(first, (datetime.datetime, datetime.time)) else None
+
         job = Job(callback,
                   interval=interval,
                   repeat=True,
                   context=context,
                   name=name,
-                  job_queue=self)
+                  job_queue=self,
+                  tzinfo=tzinfo)
         self._put(job, time_spec=first)
         return job
 
+    def run_monthly(self, callback, when, day, context=None, name=None, day_is_strict=True):
+        """Creates a new ``Job`` that runs on a monthly basis and adds it to the queue.
+
+        Args:
+            callback (:obj:`callable`):  The callback function that should be executed by the new
+                job. Callback signature for context based API:
+
+                    ``def callback(CallbackContext)``
+
+                ``context.job`` is the :class:`telegram.ext.Job` instance. It can be used to access
+                its ``job.context`` or change it to a repeating job.
+            when (:obj:`datetime.time`): Time of day at which the job should run. If the timezone
+                (``when.tzinfo``) is ``None``, UTC will be assumed. This will also implicitly
+                define ``Job.tzinfo``.
+            day (:obj:`int`): Defines the day of the month whereby the job would run. It should
+                be within the range of 1 and 31, inclusive.
+            context (:obj:`object`, optional): Additional data needed for the callback function.
+                Can be accessed through ``job.context`` in the callback. Defaults to ``None``.
+            name (:obj:`str`, optional): The name of the new job. Defaults to
+                ``callback.__name__``.
+            day_is_strict (:obj:`bool`, optional): If ``False`` and day > month.days, will pick
+                the last day in the month. Defaults to ``True``.
+
+        Returns:
+            :class:`telegram.ext.Job`: The new ``Job`` instance that has been added to the job
+            queue.
+
+        """
+        tzinfo = when.tzinfo if isinstance(when, (datetime.datetime, datetime.time)) else None
+        if 1 <= day <= 31:
+            next_dt = self._get_next_month_date(day, day_is_strict, when, allow_now=True)
+            job = Job(callback, repeat=False, context=context, name=name, job_queue=self,
+                      is_monthly=True, day_is_strict=day_is_strict, tzinfo=tzinfo)
+            self._put(job, time_spec=next_dt)
+            return job
+        else:
+            raise ValueError("The elements of the 'day' argument should be from 1 up to"
+                             " and including 31")
+
+    def _get_next_month_date(self, day, day_is_strict, when, allow_now=False):
+        """This method returns the date that the next monthly job should be scheduled.
+
+        Args:
+           day (:obj:`int`): The day of the month the job should run.
+           day_is_strict (:obj:`bool`):
+               Specification as to whether the specified day of job should be strictly
+               respected. If day_is_strict is ``True`` it ignores months whereby the
+               specified date does not exist (e.g February 31st). If it set to ``False``,
+               it returns the last valid date of the month instead. For example,
+               if the user runs a job on the 31st of every month, and sets
+               the day_is_strict variable to ``False``, April, for example,
+               the job would run on April 30th.
+           when (:obj:`datetime.time`): Time of day at which the job should run. If the
+               timezone (``time.tzinfo``) is ``None``, UTC will be assumed.
+           allow_now (:obj:`bool`): Whether executing the job right now is a feasible options.
+               For stability reasons, this defaults to :obj:`False`, but it needs to be :obj:`True`
+               on initializing a job.
+
+        """
+        dt = datetime.datetime.now(tz=when.tzinfo or datetime.timezone.utc)
+        dt_time = dt.time().replace(tzinfo=when.tzinfo)
+        days_in_current_month = calendar.monthrange(dt.year, dt.month)[1]
+        days_till_months_end = days_in_current_month - dt.day
+        if days_in_current_month < day:
+            # if the day does not exist in the current month (e.g Feb 31st)
+            if day_is_strict is False:
+                # set day as last day of month instead
+                next_dt = dt + datetime.timedelta(days=days_till_months_end)
+            else:
+                # else set as day in subsequent month. Subsequent month is
+                # guaranteed to have the date, if current month does not have the date.
+                next_dt = dt + datetime.timedelta(days=days_till_months_end + day)
+        else:
+            # if the day exists in the current month
+            if dt.day < day:
+                # day is upcoming
+                next_dt = dt + datetime.timedelta(day - dt.day)
+            elif dt.day > day or (dt.day == day and ((not allow_now and dt_time >= when)
+                                                     or (allow_now and dt_time > when))):
+                # run next month if day has already passed
+                next_year = dt.year + 1 if dt.month == 12 else dt.year
+                next_month = 1 if dt.month == 12 else dt.month + 1
+                days_in_next_month = calendar.monthrange(next_year, next_month)[1]
+                next_month_has_date = days_in_next_month >= day
+                if next_month_has_date:
+                    next_dt = dt + datetime.timedelta(days=days_till_months_end + day)
+                elif day_is_strict:
+                    # schedule the subsequent month if day is strict
+                    next_dt = dt + datetime.timedelta(
+                        days=days_till_months_end + days_in_next_month + day)
+                else:
+                    # schedule in the next month last date if day is not strict
+                    next_dt = dt + datetime.timedelta(days=days_till_months_end
+                                                      + days_in_next_month)
+
+            else:
+                # day is today but time has not yet come
+                next_dt = dt
+
+        # Set the correct time
+        next_dt = next_dt.replace(hour=when.hour, minute=when.minute, second=when.second,
+                                  microsecond=when.microsecond)
+        # fold is new in Py3.6
+        if hasattr(next_dt, 'fold'):
+            next_dt = next_dt.replace(fold=when.fold)
+        return next_dt
+
     def run_daily(self, callback, time, days=Days.EVERY_DAY, context=None, name=None):
         """Creates a new ``Job`` that runs on a daily basis and adds it to the queue.
 
@@ -215,6 +342,7 @@ class JobQueue(object):
                 its ``job.context`` or change it to a repeating job.
             time (:obj:`datetime.time`): Time of day at which the job should run. If the timezone
                 (``time.tzinfo``) is ``None``, UTC will be assumed.
+                ``time.tzinfo`` will implicitly define ``Job.tzinfo``.
             days (Tuple[:obj:`int`], optional): Defines on which days of the week the job should
                 run. Defaults to ``EVERY_DAY``
             context (:obj:`object`, optional): Additional data needed for the callback function.
@@ -226,7 +354,7 @@ class JobQueue(object):
             :class:`telegram.ext.Job`: The new ``Job`` instance that has been added to the job
             queue.
 
-        Notes:
+        Note:
              Daily is just an alias for "24 Hours". That means that if DST changes during that
              interval, the job might not run at the time one would expect. It is always recommended
              to pin servers to UTC time, then time related behaviour can always be expected.
@@ -285,9 +413,10 @@ class JobQueue(object):
             if job.enabled:
                 try:
                     current_week_day = datetime.datetime.now(job.tzinfo).date().weekday()
-                    if any(day == current_week_day for day in job.days):
+                    if current_week_day in job.days:
                         self.logger.debug('Running job %s', job.name)
                         job.run(self._dispatcher)
+                        self._dispatcher.update_persistence()
 
                 except Exception:
                     self.logger.exception('An uncaught error was raised while executing job %s',
@@ -297,7 +426,13 @@ class JobQueue(object):
 
             if job.repeat and not job.removed:
                 self._put(job, previous_t=t)
+            elif job.is_monthly and not job.removed:
+                dt = datetime.datetime.now(tz=job.tzinfo)
+                dt_time = dt.time().replace(tzinfo=job.tzinfo)
+                self._put(job, time_spec=self._get_next_month_date(dt.day, job.day_is_strict,
+                                                                   dt_time))
             else:
+                job._set_next_t(None)
                 self.logger.debug('Dropping non-repeating or removed job %s', job.name)
 
     def start(self):
@@ -364,6 +499,8 @@ class Job(object):
         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.
+        is_monthly (:obj: `bool`): Optional. Indicates whether it is a monthly job.
+        day_is_strict (:obj: `bool`): Optional. Indicates whether the monthly jobs day is strict.
 
     Args:
         callback (:obj:`callable`): The callback function that should be executed by the new job.
@@ -390,6 +527,11 @@ class Job(object):
         tzinfo (:obj:`datetime.tzinfo`, optional): timezone associated to this job. Used when
             checking the day of the week to determine whether a job should run (only relevant when
             ``days is not Days.EVERY_DAY``). Defaults to UTC.
+        is_monthly (:obj:`bool`, optional): If this job is supposed to be a monthly scheduled job.
+            Defaults to ``False``.
+        day_is_strict (:obj:`bool`, optional): If ``False`` and day > month.days, will pick the
+            last day in the month. Defaults to ``True``. Only relevant when ``is_monthly`` is
+            ``True``.
     """
 
     def __init__(self,
@@ -400,7 +542,9 @@ class Job(object):
                  days=Days.EVERY_DAY,
                  name=None,
                  job_queue=None,
-                 tzinfo=_UTC):
+                 tzinfo=None,
+                 is_monthly=False,
+                 day_is_strict=True):
 
         self.callback = callback
         self.context = context
@@ -409,11 +553,14 @@ class Job(object):
         self._repeat = None
         self._interval = None
         self.interval = interval
+        self._next_t = None
         self.repeat = repeat
+        self.is_monthly = is_monthly
+        self.day_is_strict = day_is_strict
 
         self._days = None
         self.days = days
-        self.tzinfo = tzinfo
+        self.tzinfo = tzinfo or datetime.timezone.utc
 
         self._job_queue = weakref.proxy(job_queue) if job_queue is not None else None
 
@@ -435,6 +582,7 @@ class Job(object):
 
         """
         self._remove.set()
+        self._next_t = None
 
     @property
     def removed(self):
@@ -468,8 +616,8 @@ class Job(object):
             raise ValueError("The 'interval' can not be 'None' when 'repeat' is set to 'True'")
 
         if not (interval is None or isinstance(interval, (Number, datetime.timedelta))):
-            raise ValueError("The 'interval' must be of type 'datetime.timedelta',"
-                             " 'int' or 'float'")
+            raise TypeError("The 'interval' must be of type 'datetime.timedelta',"
+                            " 'int' or 'float'")
 
         self._interval = interval
 
@@ -482,6 +630,27 @@ class Job(object):
         else:
             return interval
 
+    @property
+    def next_t(self):
+        """
+        :obj:`datetime.datetime`: Datetime for the next job execution.
+            Datetime is localized according to :attr:`tzinfo`.
+            If job is removed or already ran it equals to ``None``.
+
+        """
+        return datetime.datetime.fromtimestamp(self._next_t, self.tzinfo) if self._next_t else None
+
+    def _set_next_t(self, next_t):
+        if isinstance(next_t, datetime.datetime):
+            # Set timezone to UTC in case datetime is in local timezone.
+            next_t = next_t.astimezone(datetime.timezone.utc)
+            next_t = to_float_timestamp(next_t)
+        elif not (isinstance(next_t, Number) or next_t is None):
+            raise TypeError("The 'next_t' argument should be one of the following types: "
+                            "'float', 'int', 'datetime.datetime' or 'NoneType'")
+
+        self._next_t = next_t
+
     @property
     def repeat(self):
         """:obj:`bool`: Optional. If this job should periodically execute its callback function."""
@@ -501,10 +670,10 @@ class Job(object):
     @days.setter
     def days(self, days):
         if not isinstance(days, tuple):
-            raise ValueError("The 'days' argument should be of type 'tuple'")
+            raise TypeError("The 'days' argument should be of type 'tuple'")
 
         if not all(isinstance(day, int) for day in days):
-            raise ValueError("The elements of the 'days' argument should be of type 'int'")
+            raise TypeError("The elements of the 'days' argument should be of type 'int'")
 
         if not all(0 <= day <= 6 for day in days):
             raise ValueError("The elements of the 'days' argument should be from 0 up to and "

telegram/ext/messagequeue.py

@@ -249,7 +249,7 @@ class MessageQueue(object):
                 ``DelayQueue`` (if set to ``False``), resulting in needed delays to avoid
                 hitting specified limits. Defaults to ``False``.
 
-        Notes:
+        Note:
             Method is designed to accept ``telegram.utils.promise.Promise`` as ``promise``
             argument, but other callables could be used too. For example, lambdas or simple
             functions could be used to wrap original func to be called with needed args. In that

telegram/ext/picklepersistence.py

@@ -224,6 +224,8 @@ class PicklePersistence(BasePersistence):
             user_id (:obj:`int`): The user the data might have been changed for.
             data (:obj:`dict`): The :attr:`telegram.ext.dispatcher.user_data` [user_id].
         """
+        if self.user_data is None:
+            self.user_data = defaultdict(dict)
         if self.user_data.get(user_id) == data:
             return
         self.user_data[user_id] = data
@@ -242,6 +244,8 @@ class PicklePersistence(BasePersistence):
             chat_id (:obj:`int`): The chat the data might have been changed for.
             data (:obj:`dict`): The :attr:`telegram.ext.dispatcher.chat_data` [chat_id].
         """
+        if self.chat_data is None:
+            self.chat_data = defaultdict(dict)
         if self.chat_data.get(chat_id) == data:
             return
         self.chat_data[chat_id] = data

telegram/ext/updater.py

@@ -570,9 +570,9 @@ class Updater(object):
         """Blocks until one of the signals are received and stops the updater.
 
         Args:
-            stop_signals (:obj:`iterable`): Iterable containing signals from the signal module that
-                should be subscribed to. Updater.stop() will be called on receiving one of those
-                signals. Defaults to (``SIGINT``, ``SIGTERM``, ``SIGABRT``).
+            stop_signals (:obj:`list` | :obj:`tuple`): List containing signals from the signal
+                module that should be subscribed to. Updater.stop() will be called on receiving one
+                of those signals. Defaults to (``SIGINT``, ``SIGTERM``, ``SIGABRT``).
 
         """
         for sig in stop_signals:

telegram/files/sticker.py

@@ -138,6 +138,8 @@ class StickerSet(TelegramObject):
         is_animated (:obj:`bool`): True, if the sticker set contains animated stickers.
         contains_masks (:obj:`bool`): True, if the sticker set contains masks.
         stickers (List[:class:`telegram.Sticker`]): List of all set stickers.
+        thumb (:class:`telegram.PhotoSize`): Optional. Sticker set thumbnail in the .WEBP or .TGS
+            format
 
     Args:
         name (:obj:`str`): Sticker set name.
@@ -145,15 +147,20 @@ class StickerSet(TelegramObject):
         is_animated (:obj:`bool`): True, if the sticker set contains animated stickers.
         contains_masks (:obj:`bool`): True, if the sticker set contains masks.
         stickers (List[:class:`telegram.Sticker`]): List of all set stickers.
+        thumb (:class:`telegram.PhotoSize`, optional): Sticker set thumbnail in the .WEBP or .TGS
+            format
 
     """
 
-    def __init__(self, name, title, is_animated, contains_masks, stickers, bot=None, **kwargs):
+    def __init__(self, name, title, is_animated, contains_masks, stickers, bot=None, thumb=None,
+                 **kwargs):
         self.name = name
         self.title = title
         self.is_animated = is_animated
         self.contains_masks = contains_masks
         self.stickers = stickers
+        # Optionals
+        self.thumb = thumb
 
         self._id_attrs = (self.name,)
 
@@ -164,6 +171,7 @@ class StickerSet(TelegramObject):
 
         data = super(StickerSet, StickerSet).de_json(data, bot)
 
+        data['thumb'] = PhotoSize.de_json(data.get('thumb'), bot)
         data['stickers'] = Sticker.de_list(data.get('stickers'), bot)
 
         return StickerSet(bot=bot, **data)
@@ -187,7 +195,7 @@ class MaskPosition(TelegramObject):
             size, from top to bottom.
         scale (:obj:`float`): Mask scaling coefficient. For example, 2.0 means double size.
 
-    Notes:
+    Note:
         :attr:`type` should be one of the following: `forehead`, `eyes`, `mouth` or `chin`. You can
         use the classconstants for those.
 

telegram/inline/inlinekeyboardbutton.py

@@ -30,27 +30,28 @@ class InlineKeyboardButton(TelegramObject):
 
     Attributes:
         text (:obj:`str`): Label text on the button.
-        url (:obj:`str`): Optional. HTTP url to be opened when button is pressed.
+        url (:obj:`str`): Optional. HTTP or tg:// url to be opened when button is pressed.
         login_url (:class:`telegram.LoginUrl`) Optional. An HTTP URL used to automatically
-            authorize the user.
+            authorize the user. Can be used as a replacement for the Telegram Login Widget.
         callback_data (:obj:`str`): Optional. Data to be sent in a callback query to the bot when
             button is pressed, UTF-8 1-64 bytes.
         switch_inline_query (:obj:`str`): Optional. Will prompt the user to select one of their
             chats, open that chat and insert the bot's username and the specified inline query in
-            the input field.
+            the input field. Can be empty, in which case just the bot’s username will be inserted.
         switch_inline_query_current_chat (:obj:`str`): Optional. Will insert the bot's username and
-            the specified inline query in the current chat's input field.
+            the specified inline query in the current chat's input field. Can be empty, in which
+            case just the bot’s username will be inserted.
         callback_game (:class:`telegram.CallbackGame`): Optional. Description of the game that will
             be launched when the user presses the button.
         pay (:obj:`bool`): Optional. Specify True, to send a Pay button.
 
     Args:
         text (:obj:`str`): Label text on the button.
-        url (:obj:`str`): HTTP url to be opened when button is pressed.
+        url (:obj:`str`): HTTP or tg:// url to be opened when button is pressed.
         login_url (:class:`telegram.LoginUrl`, optional) An HTTP URL used to automatically
-            authorize the user.
+            authorize the user. Can be used as a replacement for the Telegram Login Widget.
         callback_data (:obj:`str`, optional): Data to be sent in a callback query to the bot when
-            button is pressed, 1-64 UTF-8 bytes.
+            button is pressed, UTF-8 1-64 bytes.
         switch_inline_query (:obj:`str`, optional): If set, pressing the button will prompt the
             user to select one of their chats, open that chat and insert the bot's username and the
             specified inline query in the input field. Can be empty, in which case just the bot's

telegram/inline/inlinequeryresultaudio.py

@@ -33,9 +33,9 @@ class InlineQueryResultAudio(InlineQueryResult):
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         audio_url (:obj:`str`): A valid URL for the audio file.
         title (:obj:`str`): Title.
-        performer (:obj:`str`): Optional. Caption, 0-200 characters.
-        audio_duration (:obj:`str`): Optional. Performer.
-        caption (:obj:`str`): Optional. Audio duration in seconds.
+        performer (:obj:`str`): Optional. Performer.
+        audio_duration (:obj:`str`): Optional. Audio duration in seconds.
+        caption (:obj:`str`): Optional. Caption, 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.
@@ -48,9 +48,9 @@ class InlineQueryResultAudio(InlineQueryResult):
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         audio_url (:obj:`str`): A valid URL for the audio file.
         title (:obj:`str`): Title.
-        performer (:obj:`str`, optional): Caption, 0-200 characters.
-        audio_duration (:obj:`str`, optional): Performer.
-        caption (:obj:`str`, optional): Audio duration in seconds.
+        performer (:obj:`str`, optional): Performer.
+        audio_duration (:obj:`str`, optional): Audio duration in seconds.
+        caption (:obj:`str`, optional): Caption, 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.

telegram/inline/inlinequeryresultcachedaudio.py

@@ -26,13 +26,13 @@ class InlineQueryResultCachedAudio(InlineQueryResult):
     """
     Represents a link to an mp3 audio file stored on the Telegram servers. By default, this audio
     file will be sent by the user. Alternatively, you can use :attr:`input_message_content` to
-    send amessage with the specified content instead of the audio.
+    send a message with the specified content instead of the audio.
 
     Attributes:
         type (:obj:`str`): 'audio'.
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         audio_file_id (:obj:`str`): A valid file identifier for the audio file.
-        caption (:obj:`str`): Optional. Caption, 0-1024 characters
+        caption (:obj:`str`): Optional. Caption, 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.
@@ -44,7 +44,7 @@ class InlineQueryResultCachedAudio(InlineQueryResult):
     Args:
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         audio_file_id (:obj:`str`): A valid file identifier for the audio file.
-        caption (:obj:`str`, optional): Caption, 0-1024 characters
+        caption (:obj:`str`, optional): Caption, 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.

telegram/inline/inlinequeryresultcacheddocument.py

@@ -34,7 +34,8 @@ class InlineQueryResultCachedDocument(InlineQueryResult):
         title (:obj:`str`): Title for the result.
         document_file_id (:obj:`str`): A valid file identifier for the file.
         description (:obj:`str`): Optional. Short description of the result.
-        caption (:obj:`str`): Optional. Caption, 0-1024 characters
+        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.
@@ -48,7 +49,8 @@ class InlineQueryResultCachedDocument(InlineQueryResult):
         title (:obj:`str`): Title for the result.
         document_file_id (:obj:`str`): A valid file identifier for the file.
         description (:obj:`str`, optional): Short description of the result.
-        caption (:obj:`str`, optional): Caption, 0-1024 characters
+        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.

telegram/inline/inlinequeryresultcachedgif.py

@@ -34,7 +34,8 @@ class InlineQueryResultCachedGif(InlineQueryResult):
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         gif_file_id (:obj:`str`): A valid file identifier for the GIF file.
         title (:obj:`str`): Optional. Title for the result.
-        caption (:obj:`str`): Optional. Caption, 0-1024 characters
+        caption (:obj:`str`): Optional. Caption of the GIF file 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.
@@ -47,7 +48,8 @@ class InlineQueryResultCachedGif(InlineQueryResult):
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         gif_file_id (:obj:`str`): A valid file identifier for the GIF file.
         title (:obj:`str`, optional): Title for the result.caption (:obj:`str`, optional):
-        caption (:obj:`str`, optional): Caption, 0-1024 characters
+        caption (:obj:`str`, optional): Caption of the GIF file 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.

telegram/inline/inlinequeryresultcachedmpeg4gif.py

@@ -34,7 +34,8 @@ class InlineQueryResultCachedMpeg4Gif(InlineQueryResult):
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         mpeg4_file_id (:obj:`str`): A valid file identifier for the MP4 file.
         title (:obj:`str`): Optional. Title for the result.
-        caption (:obj:`str`): Optional. Caption, 0-1024 characters
+        caption (:obj:`str`): Optional. Caption of the MPEG-4 file to be sent, 0-1024 characters
+            after entities parsing.
         parse_mode (:obj:`str`): 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.
@@ -47,7 +48,8 @@ class InlineQueryResultCachedMpeg4Gif(InlineQueryResult):
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         mpeg4_file_id (:obj:`str`): A valid file identifier for the MP4 file.
         title (:obj:`str`, optional): Title for the result.
-        caption (:obj:`str`, optional): Caption, 0-1024 characters
+        caption (:obj:`str`, optional): Caption of the MPEG-4 file 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.

telegram/inline/inlinequeryresultcachedphoto.py

@@ -35,7 +35,8 @@ class InlineQueryResultCachedPhoto(InlineQueryResult):
         photo_file_id (:obj:`str`): A valid file identifier of the photo.
         title (:obj:`str`): Optional. Title for the result.
         description (:obj:`str`): Optional. Short description of the result.
-        caption (:obj:`str`): Optional. Caption, 0-1024 characters
+        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.
@@ -49,7 +50,8 @@ class InlineQueryResultCachedPhoto(InlineQueryResult):
         photo_file_id (:obj:`str`): A valid file identifier of the photo.
         title (:obj:`str`, optional): Title for the result.
         description (:obj:`str`, optional): Short description of the result.
-        caption (:obj:`str`, optional): Caption, 0-1024 characters
+        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.

telegram/inline/inlinequeryresultcachedsticker.py

@@ -37,8 +37,8 @@ class InlineQueryResultCachedSticker(InlineQueryResult):
             message to be sent instead of the sticker.
 
     Args:
-        id (:obj:`str`):
-        sticker_file_id (:obj:`str`):
+        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
+        sticker_file_id (:obj:`str`): A valid file identifier of the sticker.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the

telegram/inline/inlinequeryresultcachedvideo.py

@@ -35,7 +35,8 @@ class InlineQueryResultCachedVideo(InlineQueryResult):
         video_file_id (:obj:`str`): A valid file identifier for the video file.
         title (:obj:`str`): Title for the result.
         description (:obj:`str`): Optional. Short description of the result.
-        caption (:obj:`str`): Optional. Caption, 0-1024 characters after entities parsing.
+        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.
@@ -49,7 +50,8 @@ class InlineQueryResultCachedVideo(InlineQueryResult):
         video_file_id (:obj:`str`): A valid file identifier for the video file.
         title (:obj:`str`): Title for the result.
         description (:obj:`str`, optional): Short description of the result.
-        caption (:obj:`str`, optional): Caption, 0-1024 characters after entities parsing.
+        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.

telegram/inline/inlinequeryresultdocument.py

@@ -33,7 +33,8 @@ class InlineQueryResultDocument(InlineQueryResult):
         type (:obj:`str`): 'document'.
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         title (:obj:`str`): Title for the result.
-        caption (:obj:`str`): Optional. Caption, 0-1024 characters
+        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.
@@ -52,7 +53,8 @@ class InlineQueryResultDocument(InlineQueryResult):
     Args:
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         title (:obj:`str`): Title for the result.
-        caption (:obj:`str`, optional): Caption, 0-1024 characters
+        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.
@@ -60,9 +62,9 @@ class InlineQueryResultDocument(InlineQueryResult):
         mime_type (:obj:`str`): Mime type of the content of the file, either "application/pdf"
             or "application/zip".
         description (:obj:`str`, optional): Short description of the result.
-        reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
+        reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
-        input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
+        input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
             message to be sent instead of the file.
         thumb_url (:obj:`str`, optional): URL of the thumbnail (jpeg only) for the file.
         thumb_width (:obj:`int`, optional): Thumbnail width.

telegram/inline/inlinequeryresultgif.py

@@ -37,14 +37,15 @@ class InlineQueryResultGif(InlineQueryResult):
         gif_duration (:obj:`int`): Optional. Duration of the GIF.
         thumb_url (:obj:`str`): URL of the static thumbnail for the result (jpeg or gif).
         title (:obj:`str`): Optional. Title for the result.
-        caption (:obj:`str`): Optional. Caption, 0-1024 characters
+        caption (:obj:`str`): Optional. Caption of the GIF file 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.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
-            message to be sent instead of the gif.
+            message to be sent instead of the GIF animation.
 
     Args:
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
@@ -53,15 +54,16 @@ class InlineQueryResultGif(InlineQueryResult):
         gif_height (:obj:`int`, optional): Height of the GIF.
         gif_duration (:obj:`int`, optional): Duration of the GIF
         thumb_url (:obj:`str`): URL of the static thumbnail for the result (jpeg or gif).
-        title (:obj:`str`, optional): Title for the result.caption (:obj:`str`, optional):
-        caption (:obj:`str`, optional): Caption, 0-1024 characters
+        title (:obj:`str`, optional): Title for the result.
+        caption (:obj:`str`, optional): Caption of the GIF file 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.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
-            message to be sent instead of the gif.
+            message to be sent instead of the GIF animation.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     """

telegram/inline/inlinequeryresultmpeg4gif.py

@@ -38,14 +38,15 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult):
         mpeg4_duration (:obj:`int`): Optional. Video duration.
         thumb_url (:obj:`str`): URL of the static thumbnail (jpeg or gif) for the result.
         title (:obj:`str`): Optional. Title for the result.
-        caption (:obj:`str`): Optional. Caption, 0-1024 characters
+        caption (:obj:`str`): Optional. Caption of the MPEG-4 file 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.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
-            message to be sent instead of the MPEG-4 file.
+            message to be sent instead of the video animation.
 
     Args:
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
@@ -55,14 +56,15 @@ class InlineQueryResultMpeg4Gif(InlineQueryResult):
         mpeg4_duration (:obj:`int`, optional): Video duration.
         thumb_url (:obj:`str`): URL of the static thumbnail (jpeg or gif) for the result.
         title (:obj:`str`, optional): Title for the result.
-        caption (:obj:`str`, optional): Caption, 0-1024 characters
+        caption (:obj:`str`, optional): Caption of the MPEG-4 file 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.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
-            message to be sent instead of the MPEG-4 file.
+            message to be sent instead of the video animation.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     """

telegram/inline/inlinequeryresultphoto.py

@@ -38,7 +38,8 @@ class InlineQueryResultPhoto(InlineQueryResult):
         photo_height (:obj:`int`): Optional. Height of the photo.
         title (:obj:`str`): Optional. Title for the result.
         description (:obj:`str`): Optional. Short description of the result.
-        caption (:obj:`str`): Optional. Caption, 0-1024 characters
+        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.
@@ -56,7 +57,8 @@ class InlineQueryResultPhoto(InlineQueryResult):
         photo_height (:obj:`int`, optional): Height of the photo.
         title (:obj:`str`, optional): Title for the result.
         description (:obj:`str`, optional): Short description of the result.
-        caption (:obj:`str`, optional): Caption, 0-1024 characters
+        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.

telegram/inline/inlinequeryresultvideo.py

@@ -29,6 +29,10 @@ class InlineQueryResultVideo(InlineQueryResult):
     :attr:`input_message_content` to send a message with the specified content instead of
     the video.
 
+    Note:
+        If an InlineQueryResultVideo message contains an embedded video (e.g., YouTube), you must
+        replace its content using :attr:`input_message_content`.
+
     Attributes:
         type (:obj:`str`): 'video'.
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
@@ -36,7 +40,8 @@ class InlineQueryResultVideo(InlineQueryResult):
         mime_type (:obj:`str`): Mime type of the content of video url, "text/html" or "video/mp4".
         thumb_url (:obj:`str`): URL of the thumbnail (jpeg only) for the video.
         title (:obj:`str`): Title for the result.
-        caption (:obj:`str`): Optional. Caption, 0-1024 characters
+        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.
@@ -47,7 +52,9 @@ class InlineQueryResultVideo(InlineQueryResult):
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
-            message to be sent instead of the video.
+            message to be sent instead of the video. This field is required if
+            InlineQueryResultVideo is used to send an HTML-page as a result
+            (e.g., a YouTube video).
 
     Args:
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
@@ -66,7 +73,9 @@ class InlineQueryResultVideo(InlineQueryResult):
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
-            message to be sent instead of the video.
+            message to be sent instead of the video. This field is required if
+            InlineQueryResultVideo is used to send an HTML-page as a result
+            (e.g., a YouTube video).
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     """

telegram/inline/inlinequeryresultvoice.py

@@ -33,30 +33,30 @@ class InlineQueryResultVoice(InlineQueryResult):
         type (:obj:`str`): 'voice'.
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         voice_url (:obj:`str`): A valid URL for the voice recording.
-        title (:obj:`str`): Voice message title.
+        title (:obj:`str`): Recording title.
         caption (:obj:`str`): Optional. Caption, 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
+            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
             in :class:`telegram.ParseMode` for the available modes.
         voice_duration (:obj:`int`): Optional. Recording duration in seconds.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`): Optional. Content of the
-            message to be sent instead of the voice.
+            message to be sent instead of the voice recording.
 
     Args:
         id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
         voice_url (:obj:`str`): A valid URL for the voice recording.
-        title (:obj:`str`): Voice message title.
+        title (:obj:`str`): Recording title.
         caption (:obj:`str`, optional): Caption, 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
+            bold, italic, fixed-width text or inline URLs in the media caption. See the constants
             in :class:`telegram.ParseMode` for the available modes.
         voice_duration (:obj:`int`, optional): Recording duration in seconds.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message.
         input_message_content (:class:`telegram.InputMessageContent`, optional): Content of the
-            message to be sent instead of the voice.
+            message to be sent instead of the voice recording.
         **kwargs (:obj:`dict`): Arbitrary keyword arguments.
 
     """

telegram/message.py

@@ -23,7 +23,7 @@ from html import escape
 
 from telegram import (Animation, Audio, Contact, Document, Chat, Location, PhotoSize, Sticker,
                       TelegramObject, User, Video, Voice, Venue, MessageEntity, Game, Invoice,
-                      SuccessfulPayment, VideoNote, PassportData, Poll, InlineKeyboardMarkup)
+                      SuccessfulPayment, VideoNote, PassportData, Poll, InlineKeyboardMarkup, Dice)
 from telegram import ParseMode
 from telegram.utils.helpers import escape_markdown, to_timestamp, from_timestamp
 
@@ -106,6 +106,7 @@ class Message(TelegramObject):
         passport_data (:class:`telegram.PassportData`): Optional. Telegram Passport data.
         poll (:class:`telegram.Poll`): Optional. Message is a native poll,
             information about the poll.
+        dice (:class:`telegram.Dice`): Optional. Message is a dice.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
             to the message.
         bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
@@ -199,7 +200,7 @@ class Message(TelegramObject):
             smaller than 52 bits, so a signed 64 bit integer or double-precision float type are
             safe for storing this identifier.
         pinned_message (:class:`telegram.message`, optional): Specified message was pinned. Note
-            that the Message object in this field will not contain further attr:`reply_to_message`
+            that the Message object in this field will not contain further :attr:`reply_to_message`
             fields even if it is itself a reply.
         invoice (:class:`telegram.Invoice`, optional): Message is an invoice for a payment,
             information about the invoice.
@@ -214,6 +215,7 @@ class Message(TelegramObject):
         passport_data (:class:`telegram.PassportData`, optional): Telegram Passport data.
         poll (:class:`telegram.Poll`, optional): Message is a native poll,
             information about the poll.
+        dice (:class:`telegram.Dice`, optional): Message is a dice with random value from 1 to 6.
         reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
             to the message. login_url buttons are represented as ordinary url buttons.
         default_quote (:obj:`bool`, optional): Default setting for the `quote` parameter of the
@@ -229,7 +231,7 @@ class Message(TelegramObject):
     MESSAGE_TYPES = ['text', 'new_chat_members', 'left_chat_member', 'new_chat_title',
                      'new_chat_photo', 'delete_chat_photo', 'group_chat_created',
                      'supergroup_chat_created', 'channel_chat_created', 'migrate_to_chat_id',
-                     'migrate_from_chat_id', 'pinned_message',
+                     'migrate_from_chat_id', 'pinned_message', 'poll', 'dice',
                      'passport_data'] + ATTACHMENT_TYPES
 
     def __init__(self,
@@ -282,6 +284,7 @@ class Message(TelegramObject):
                  reply_markup=None,
                  bot=None,
                  default_quote=None,
+                 dice=None,
                  **kwargs):
         # Required
         self.message_id = int(message_id)
@@ -331,6 +334,7 @@ class Message(TelegramObject):
         self.animation = animation
         self.passport_data = passport_data
         self.poll = poll
+        self.dice = dice
         self.reply_markup = reply_markup
         self.bot = bot
         self.default_quote = default_quote
@@ -404,6 +408,7 @@ class Message(TelegramObject):
         data['successful_payment'] = SuccessfulPayment.de_json(data.get('successful_payment'), bot)
         data['passport_data'] = PassportData.de_json(data.get('passport_data'), bot)
         data['poll'] = Poll.de_json(data.get('poll'), bot)
+        data['dice'] = Dice.de_json(data.get('dice'), bot)
         data['reply_markup'] = InlineKeyboardMarkup.de_json(data.get('reply_markup'), bot)
 
         return cls(bot=bot, **data)
@@ -808,6 +813,23 @@ class Message(TelegramObject):
         self._quote(kwargs)
         return self.bot.send_poll(self.chat_id, *args, **kwargs)
 
+    def reply_dice(self, *args, **kwargs):
+        """Shortcut for::
+
+            bot.send_dice(update.message.chat_id, *args, **kwargs)
+
+        Keyword Args:
+            quote (:obj:`bool`, optional): If set to ``True``, the dice is sent as an actual reply
+                to this message. If ``reply_to_message_id`` is passed in ``kwargs``, this parameter
+                will be ignored. Default: ``True`` in group chats and ``False`` in private chats.
+
+        Returns:
+            :class:`telegram.Message`: On success, instance representing the message posted.
+
+        """
+        self._quote(kwargs)
+        return self.bot.send_dice(self.chat_id, *args, **kwargs)
+
     def forward(self, chat_id, *args, **kwargs):
         """Shortcut for::
 

telegram/passport/data.py

@@ -32,10 +32,12 @@ class PersonalDetails(TelegramObject):
         country_code (:obj:`str`): Citizenship (ISO 3166-1 alpha-2 country code).
         residence_country_code (:obj:`str`): Country of residence (ISO 3166-1 alpha-2 country
             code).
-        first_name (:obj:`str`): First Name in the language of the user's country of residence.
-        middle_name (:obj:`str`): Optional. Middle Name in the language of the user's country of
+        first_name_native (:obj:`str`): First Name in the language of the user's country of
+            residence.
+        middle_name_native (:obj:`str`): Optional. Middle Name in the language of the user's
+            country of residence.
+        last_name_native (:obj:`str`): Last Name in the language of the user's country of
             residence.
-        last_name (:obj:`str`): Last Name in the language of the user's country of residence.
     """
 
     def __init__(self, first_name, last_name, birth_date, gender, country_code,

telegram/poll.py

@@ -19,7 +19,10 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram Poll."""
 
-from telegram import (TelegramObject, User)
+import sys
+
+from telegram import (TelegramObject, User, MessageEntity)
+from telegram.utils.helpers import to_timestamp, from_timestamp
 
 
 class PollOption(TelegramObject):
@@ -95,6 +98,14 @@ class Poll(TelegramObject):
         type (:obj:`str`): Poll type, currently can be :attr:`REGULAR` or :attr:`QUIZ`.
         allows_multiple_answers (:obj:`bool`): True, if the poll allows multiple answers.
         correct_option_id (:obj:`int`): Optional. Identifier of the correct answer option.
+        explanation (:obj:`str`): Optional. Text that is shown when a user chooses an incorrect
+            answer or taps on the lamp icon in a quiz-style poll.
+        explanation_entities (List[:class:`telegram.MessageEntity`]): Optional. Special entities
+            like usernames, URLs, bot commands, etc. that appear in the :attr:`explanation`.
+        open_period (:obj:`int`): Optional. Amount of time in seconds the poll will be active
+            after creation.
+        close_date (:obj:`datetime.datetime`): Optional. Point in time when the poll will be
+            automatically closed.
 
     Args:
         id (:obj:`str`): Unique poll identifier.
@@ -107,11 +118,32 @@ class Poll(TelegramObject):
         correct_option_id (:obj:`int`, optional): 0-based identifier of the correct answer option.
             Available only for polls in the quiz mode, which are closed, or was sent (not
             forwarded) by the bot or to the private chat with the bot.
+        explanation (:obj:`str`, optional): Text that is shown when a user chooses an incorrect
+            answer or taps on the lamp icon in a quiz-style poll, 0-200 characters.
+        explanation_entities (List[:class:`telegram.MessageEntity`], optional): Special entities
+            like usernames, URLs, bot commands, etc. that appear in the :attr:`explanation`.
+        open_period (:obj:`int`, optional): Amount of time in seconds the poll will be active
+            after creation.
+        close_date (:obj:`datetime.datetime`, optional): Point in time (Unix timestamp) when the
+            poll will be automatically closed. Converted to :obj:`datetime.datetime`.
 
     """
 
-    def __init__(self, id, question, options, total_voter_count, is_closed, is_anonymous, type,
-                 allows_multiple_answers, correct_option_id=None, **kwargs):
+    def __init__(self,
+                 id,
+                 question,
+                 options,
+                 total_voter_count,
+                 is_closed,
+                 is_anonymous,
+                 type,
+                 allows_multiple_answers,
+                 correct_option_id=None,
+                 explanation=None,
+                 explanation_entities=None,
+                 open_period=None,
+                 close_date=None,
+                 **kwargs):
         self.id = id
         self.question = question
         self.options = options
@@ -121,6 +153,10 @@ class Poll(TelegramObject):
         self.type = type
         self.allows_multiple_answers = allows_multiple_answers
         self.correct_option_id = correct_option_id
+        self.explanation = explanation
+        self.explanation_entities = explanation_entities
+        self.open_period = open_period
+        self.close_date = close_date
 
         self._id_attrs = (self.id,)
 
@@ -132,6 +168,8 @@ class Poll(TelegramObject):
         data = super(Poll, cls).de_json(data, bot)
 
         data['options'] = [PollOption.de_json(option, bot) for option in data['options']]
+        data['explanation_entities'] = MessageEntity.de_list(data.get('explanation_entities'), bot)
+        data['close_date'] = from_timestamp(data.get('close_date'))
 
         return cls(**data)
 
@@ -139,9 +177,66 @@ class Poll(TelegramObject):
         data = super(Poll, self).to_dict()
 
         data['options'] = [x.to_dict() for x in self.options]
+        if self.explanation_entities:
+            data['explanation_entities'] = [e.to_dict() for e in self.explanation_entities]
+        data['close_date'] = to_timestamp(data.get('close_date'))
 
         return data
 
+    def parse_explanation_entity(self, entity):
+        """Returns the text from a given :class:`telegram.MessageEntity`.
+
+        Note:
+            This method is present because Telegram calculates the offset and length in
+            UTF-16 codepoint pairs, which some versions of Python don't handle automatically.
+            (That is, you can't just slice ``Message.text`` with the offset and length.)
+
+        Args:
+            entity (:class:`telegram.MessageEntity`): The entity to extract the text from. It must
+                be an entity that belongs to this message.
+
+        Returns:
+            :obj:`str`: The text of the given entity.
+
+        """
+        # Is it a narrow build, if so we don't need to convert
+        if sys.maxunicode == 0xffff:
+            return self.explanation[entity.offset:entity.offset + entity.length]
+        else:
+            entity_text = self.explanation.encode('utf-16-le')
+            entity_text = entity_text[entity.offset * 2:(entity.offset + entity.length) * 2]
+
+        return entity_text.decode('utf-16-le')
+
+    def parse_explanation_entities(self, types=None):
+        """
+        Returns a :obj:`dict` that maps :class:`telegram.MessageEntity` to :obj:`str`.
+        It contains entities from this polls explanation filtered by their ``type`` attribute as
+        the key, and the text that each entity belongs to as the value of the :obj:`dict`.
+
+        Note:
+            This method should always be used instead of the :attr:`explanation_entities`
+            attribute, since it calculates the correct substring from the message text based on
+            UTF-16 codepoints. See :attr:`parse_explanation_entity` for more info.
+
+        Args:
+            types (List[:obj:`str`], optional): List of ``MessageEntity`` types as strings. If the
+                    ``type`` attribute of an entity is contained in this list, it will be returned.
+                    Defaults to :attr:`telegram.MessageEntity.ALL_TYPES`.
+
+        Returns:
+            Dict[:class:`telegram.MessageEntity`, :obj:`str`]: A dictionary of entities mapped to
+            the text that belongs to them, calculated based on UTF-16 codepoints.
+
+        """
+        if types is None:
+            types = MessageEntity.ALL_TYPES
+
+        return {
+            entity: self.parse_explanation_entity(entity)
+            for entity in self.explanation_entities if entity.type in types
+        }
+
     REGULAR = "regular"
     """:obj:`str`: 'regular'"""
     QUIZ = "quiz"

telegram/utils/helpers.py

@@ -75,46 +75,12 @@ def escape_markdown(text, version=1, entity_type=None):
 # -------- date/time related helpers --------
 # TODO: add generic specification of UTC for naive datetimes to docs
 
-if hasattr(dtm, 'timezone'):
-    # Python 3.3+
-    def _datetime_to_float_timestamp(dt_obj):
-        if dt_obj.tzinfo is None:
-            dt_obj = dt_obj.replace(tzinfo=_UTC)
-        return dt_obj.timestamp()
-
-    _UtcOffsetTimezone = dtm.timezone
-    _UTC = dtm.timezone.utc
-else:
-    # Python < 3.3 (incl 2.7)
-
-    # hardcoded timezone class (`datetime.timezone` isn't available in py2)
-    class _UtcOffsetTimezone(dtm.tzinfo):
-        def __init__(self, offset):
-            self.offset = offset
-
-        def tzname(self, dt):
-            return 'UTC +{}'.format(self.offset)
-
-        def utcoffset(self, dt):
-            return self.offset
-
-        def dst(self, dt):
-            return dtm.timedelta(0)
-
-    _UTC = _UtcOffsetTimezone(dtm.timedelta(0))
-    __EPOCH_DT = dtm.datetime.fromtimestamp(0, tz=_UTC)
-    __NAIVE_EPOCH_DT = __EPOCH_DT.replace(tzinfo=None)
-
-    # _datetime_to_float_timestamp
-    # Not using future.backports.datetime here as datetime value might be an input from the user,
-    # making every isinstace() call more delicate. So we just use our own compat layer.
-    def _datetime_to_float_timestamp(dt_obj):
-        epoch_dt = __EPOCH_DT if dt_obj.tzinfo is not None else __NAIVE_EPOCH_DT
-        return (dt_obj - epoch_dt).total_seconds()
-
-_datetime_to_float_timestamp.__doc__ = \
+def _datetime_to_float_timestamp(dt_obj):
     """Converts a datetime object to a float timestamp (with sub-second precision).
-If the datetime object is timezone-naive, it is assumed to be in UTC."""
+    If the datetime object is timezone-naive, it is assumed to be in UTC."""
+    if dt_obj.tzinfo is None:
+        dt_obj = dt_obj.replace(tzinfo=dtm.timezone.utc)
+    return dt_obj.timestamp()
 
 
 def to_float_timestamp(t, reference_timestamp=None):
@@ -196,22 +162,27 @@ def to_timestamp(dt_obj, reference_timestamp=None):
     return int(to_float_timestamp(dt_obj, reference_timestamp)) if dt_obj is not None else None
 
 
-def from_timestamp(unixtime):
+def from_timestamp(unixtime, tzinfo=dtm.timezone.utc):
     """
-    Converts an (integer) unix timestamp to a naive datetime object in UTC.
+    Converts an (integer) unix timestamp to a timezone aware datetime object.
     ``None`` s are left alone (i.e. ``from_timestamp(None)`` is ``None``).
 
     Args:
         unixtime (int): integer POSIX timestamp
+        tzinfo (:obj:`datetime.tzinfo`, optional): The timezone, the timestamp is to be converted
+            to. Defaults to UTC.
 
     Returns:
-        equivalent :obj:`datetime.datetime` value in naive UTC if ``timestamp`` is not
+        timezone aware equivalent :obj:`datetime.datetime` value if ``timestamp`` is not
         ``None``; else ``None``
     """
     if unixtime is None:
         return None
 
-    return dtm.datetime.utcfromtimestamp(unixtime)
+    if tzinfo is not None:
+        return dtm.datetime.fromtimestamp(unixtime, tz=tzinfo)
+    else:
+        return dtm.datetime.utcfromtimestamp(unixtime)
 
 # -------- end --------
 

telegram/version.py

@@ -17,4 +17,4 @@
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 
-__version__ = '12.5'
+__version__ = '12.7'

tests/bots.py

@@ -21,6 +21,9 @@ import json
 import base64
 import os
 import random
+import pytest
+from telegram.utils.request import Request
+from telegram.error import RetryAfter
 
 # Provide some public fallbacks so it's easy for contributors to run tests on their local machine
 # These bots are only able to talk in our test chats, so they are quite useless for other
@@ -30,7 +33,7 @@ FALLBACKS = [
         'token': '579694714:AAHRLL5zBVy4Blx2jRFKe1HlfnXCg08WuLY',
         'payment_provider_token': '284685063:TEST:NjQ0NjZlNzI5YjJi',
         'chat_id': '675666224',
-        'super_group_id': '-1001493296829',
+        'super_group_id': '-1001310911135',
         'channel_id': '@pythontelegrambottests',
         'bot_name': 'PTB tests fallback 1',
         'bot_username': '@ptb_fallback_1_bot'
@@ -38,7 +41,7 @@ FALLBACKS = [
         'token': '558194066:AAEEylntuKSLXj9odiv3TnX7Z5KY2J3zY3M',
         'payment_provider_token': '284685063:TEST:YjEwODQwMTFmNDcy',
         'chat_id': '675666224',
-        'super_group_id': '-1001493296829',
+        'super_group_id': '-1001221216830',
         'channel_id': '@pythontelegrambottests',
         'bot_name': 'PTB tests fallback 2',
         'bot_username': '@ptb_fallback_2_bot'
@@ -73,3 +76,17 @@ def get(name, fallback):
 
 def get_bot():
     return {k: get(k, v) for k, v in random.choice(FALLBACKS).items()}
+
+
+# Patch request to xfail on flood control errors
+original_request_wrapper = Request._request_wrapper
+
+
+def patient_request_wrapper(*args, **kwargs):
+    try:
+        return original_request_wrapper(*args, **kwargs)
+    except RetryAfter as e:
+        pytest.xfail('Not waiting for flood control: {}'.format(e))
+
+
+Request._request_wrapper = patient_request_wrapper

tests/conftest.py

@@ -31,7 +31,7 @@ from telegram import (Bot, Message, User, Chat, MessageEntity, Update,
                       InlineQuery, CallbackQuery, ShippingQuery, PreCheckoutQuery,
                       ChosenInlineResult)
 from telegram.ext import Dispatcher, JobQueue, Updater, BaseFilter, Defaults
-from telegram.utils.helpers import _UtcOffsetTimezone
+from telegram.error import BadRequest
 from tests.bots import get_bot
 
 GITHUB_ACTION = os.getenv('GITHUB_ACTION', False)
@@ -280,4 +280,27 @@ def utc_offset(request):
 
 @pytest.fixture()
 def timezone(utc_offset):
-    return _UtcOffsetTimezone(utc_offset)
+    return datetime.timezone(utc_offset)
+
+
+def expect_bad_request(func, message, reason):
+    """
+    Wrapper for testing bot functions expected to result in an :class:`telegram.error.BadRequest`.
+    Makes it XFAIL, if the specified error message is present.
+
+    Args:
+        func: The callable to be executed.
+        message: The expected message of the bad request error. If another message is present,
+            the error will be reraised.
+        reason: Explanation for the XFAIL.
+
+    Returns:
+        On success, returns the return value of :attr:`func`
+    """
+    try:
+        return func()
+    except BadRequest as e:
+        if message in str(e):
+            pytest.xfail('{}. {}'.format(reason, e))
+        else:
+            raise e

tests/test_bot.py

@@ -26,10 +26,11 @@ from future.utils import string_types
 
 from telegram import (Bot, Update, ChatAction, TelegramError, User, InlineKeyboardMarkup,
                       InlineKeyboardButton, InlineQueryResultArticle, InputTextMessageContent,
-                      ShippingOption, LabeledPrice, ChatPermissions, Poll,
-                      InlineQueryResultDocument)
+                      ShippingOption, LabeledPrice, ChatPermissions, Poll, BotCommand,
+                      InlineQueryResultDocument, Dice, MessageEntity, ParseMode)
 from telegram.error import BadRequest, InvalidToken, NetworkError, RetryAfter
 from telegram.utils.helpers import from_timestamp, escape_markdown
+from tests.conftest import expect_bad_request
 
 BASE_TIME = time.time()
 HIGHSCORE_DELTA = 1450000000
@@ -80,6 +81,7 @@ class TestBot(object):
     @pytest.mark.timeout(10)
     def test_get_me_and_properties(self, bot):
         get_me_bot = bot.get_me()
+        commands = bot.get_my_commands()
 
         assert isinstance(get_me_bot, User)
         assert get_me_bot.id == bot.id
@@ -91,6 +93,7 @@ class TestBot(object):
         assert get_me_bot.can_read_all_group_messages == bot.can_read_all_group_messages
         assert get_me_bot.supports_inline_queries == bot.supports_inline_queries
         assert 'https://t.me/{}'.format(get_me_bot.username) == bot.link
+        assert commands == bot.commands
 
     @flaky(3, 1)
     @pytest.mark.timeout(10)
@@ -174,7 +177,13 @@ class TestBot(object):
 
     @flaky(3, 1)
     @pytest.mark.timeout(10)
-    def test_send_and_stop_poll(self, bot, super_group_id):
+    @pytest.mark.parametrize('reply_markup', [
+        None,
+        InlineKeyboardMarkup.from_button(InlineKeyboardButton(text='text', callback_data='data')),
+        InlineKeyboardMarkup.from_button(
+            InlineKeyboardButton(text='text', callback_data='data')).to_dict()
+    ])
+    def test_send_and_stop_poll(self, bot, super_group_id, reply_markup):
         question = 'Is this a test?'
         answers = ['Yes', 'No', 'Maybe']
         message = bot.send_poll(chat_id=super_group_id, question=question, options=answers,
@@ -190,7 +199,10 @@ class TestBot(object):
         assert not message.poll.is_closed
         assert message.poll.type == Poll.REGULAR
 
-        poll = bot.stop_poll(chat_id=super_group_id, message_id=message.message_id, timeout=60)
+        # Since only the poll and not the complete message is returned, we can't check that the
+        # reply_markup is correct. So we just test that sending doesn't give an error.
+        poll = bot.stop_poll(chat_id=super_group_id, message_id=message.message_id,
+                             reply_markup=reply_markup, timeout=60)
         assert isinstance(poll, Poll)
         assert poll.is_closed
         assert poll.options[0].text == answers[0]
@@ -202,23 +214,86 @@ class TestBot(object):
         assert poll.question == question
         assert poll.total_voter_count == 0
 
+        explanation = '[Here is a link](https://google.com)'
+        explanation_entities = [
+            MessageEntity(MessageEntity.TEXT_LINK, 0, 14, url='https://google.com')
+        ]
         message_quiz = bot.send_poll(chat_id=super_group_id, question=question, options=answers,
-                                     type=Poll.QUIZ, correct_option_id=2, is_closed=True)
+                                     type=Poll.QUIZ, correct_option_id=2, is_closed=True,
+                                     explanation=explanation,
+                                     explanation_parse_mode=ParseMode.MARKDOWN_V2)
         assert message_quiz.poll.correct_option_id == 2
         assert message_quiz.poll.type == Poll.QUIZ
         assert message_quiz.poll.is_closed
+        assert message_quiz.poll.explanation == 'Here is a link'
+        assert message_quiz.poll.explanation_entities == explanation_entities
 
     @flaky(3, 1)
     @pytest.mark.timeout(10)
-    def test_send_game(self, bot, chat_id):
-        game_short_name = 'test_game'
-        message = bot.send_game(chat_id, game_short_name)
+    @pytest.mark.parametrize(['open_period', 'close_date'], [(5, None), (None, True)])
+    def test_send_open_period(self, bot, super_group_id, open_period, close_date):
+        question = 'Is this a test?'
+        answers = ['Yes', 'No', 'Maybe']
+        reply_markup = InlineKeyboardMarkup.from_button(
+            InlineKeyboardButton(text='text', callback_data='data'))
 
-        assert message.game
-        assert message.game.description == ('A no-op test game, for python-telegram-bot '
-                                            'bot framework testing.')
-        assert message.game.animation.file_id != ''
-        assert message.game.photo[0].file_size == 851
+        if close_date:
+            close_date = dtm.datetime.utcnow() + dtm.timedelta(seconds=5)
+
+        message = bot.send_poll(chat_id=super_group_id, question=question, options=answers,
+                                is_anonymous=False, allows_multiple_answers=True, timeout=60,
+                                open_period=open_period, close_date=close_date)
+        time.sleep(5.1)
+        new_message = bot.edit_message_reply_markup(chat_id=super_group_id,
+                                                    message_id=message.message_id,
+                                                    reply_markup=reply_markup, timeout=60)
+        assert new_message.poll.id == message.poll.id
+        assert new_message.poll.is_closed
+
+    @flaky(3, 1)
+    @pytest.mark.timeout(10)
+    @pytest.mark.parametrize('default_bot', [{'parse_mode': 'Markdown'}], indirect=True)
+    def test_send_poll_default_parse_mode(self, default_bot, super_group_id):
+        explanation = 'Italic Bold Code'
+        explanation_markdown = '_Italic_ *Bold* `Code`'
+        question = 'Is this a test?'
+        answers = ['Yes', 'No', 'Maybe']
+
+        message = default_bot.send_poll(chat_id=super_group_id, question=question, options=answers,
+                                        type=Poll.QUIZ, correct_option_id=2, is_closed=True,
+                                        explanation=explanation_markdown)
+        assert message.poll.explanation == explanation
+        assert message.poll.explanation_entities == [
+            MessageEntity(MessageEntity.ITALIC, 0, 6),
+            MessageEntity(MessageEntity.BOLD, 7, 4),
+            MessageEntity(MessageEntity.CODE, 12, 4)
+        ]
+
+        message = default_bot.send_poll(chat_id=super_group_id, question=question, options=answers,
+                                        type=Poll.QUIZ, correct_option_id=2, is_closed=True,
+                                        explanation=explanation_markdown,
+                                        explanation_parse_mode=None)
+        assert message.poll.explanation == explanation_markdown
+        assert message.poll.explanation_entities == []
+
+        message = default_bot.send_poll(chat_id=super_group_id, question=question, options=answers,
+                                        type=Poll.QUIZ, correct_option_id=2, is_closed=True,
+                                        explanation=explanation_markdown,
+                                        explanation_parse_mode='HTML')
+        assert message.poll.explanation == explanation_markdown
+        assert message.poll.explanation_entities == []
+
+    @flaky(3, 1)
+    @pytest.mark.timeout(10)
+    @pytest.mark.parametrize('emoji', Dice.ALL_EMOJI + [None])
+    def test_send_dice(self, bot, chat_id, emoji):
+        message = bot.send_dice(chat_id, emoji=emoji)
+
+        assert message.dice
+        if emoji is None:
+            assert message.dice.emoji == Dice.DICE
+        else:
+            assert message.dice.emoji == emoji
 
     @flaky(3, 1)
     @pytest.mark.timeout(10)
@@ -546,7 +621,7 @@ class TestBot(object):
         chat = bot.get_chat(super_group_id)
 
         assert chat.type == 'supergroup'
-        assert chat.title == '>>> telegram.Bot(test)'
+        assert chat.title == '>>> telegram.Bot(test) @{}'.format(bot.username)
         assert chat.id == int(super_group_id)
 
     # TODO: Add bot to group to test there too
@@ -596,6 +671,18 @@ class TestBot(object):
     def test_delete_chat_sticker_set(self):
         pass
 
+    @flaky(3, 1)
+    @pytest.mark.timeout(10)
+    def test_send_game(self, bot, chat_id):
+        game_short_name = 'test_game'
+        message = bot.send_game(chat_id, game_short_name)
+
+        assert message.game
+        assert message.game.description == ('A no-op test game, for python-telegram-bot '
+                                            'bot framework testing.')
+        assert message.game.animation.file_id != ''
+        assert message.game.photo[0].file_size == 851
+
     @flaky(3, 1)
     @pytest.mark.timeout(10)
     def test_set_game_score_1(self, bot, chat_id):
@@ -797,14 +884,20 @@ class TestBot(object):
 
     @flaky(3, 1)
     @pytest.mark.timeout(10)
-    def test_delete_chat_photo(self, bot, channel_id):
-        assert bot.delete_chat_photo(channel_id)
+    def test_set_chat_photo(self, bot, channel_id):
+        def func():
+            assert bot.set_chat_photo(channel_id, f)
+
+        with open('tests/data/telegram_test_channel.jpg', 'rb') as f:
+            expect_bad_request(func, 'Type of file mismatch', 'Telegram did not accept the file.')
 
     @flaky(3, 1)
     @pytest.mark.timeout(10)
-    def test_set_chat_photo(self, bot, channel_id):
-        with open('tests/data/telegram_test_channel.jpg', 'rb') as f:
-            assert bot.set_chat_photo(channel_id, f)
+    def test_delete_chat_photo(self, bot, channel_id):
+        def func():
+            assert bot.delete_chat_photo(channel_id)
+
+        expect_bad_request(func, 'Chat_not_modified', 'Chat photo was not set.')
 
     @flaky(3, 1)
     @pytest.mark.timeout(10)
@@ -904,3 +997,41 @@ class TestBot(object):
     def test_send_message_default_quote(self, default_bot, chat_id):
         message = default_bot.send_message(chat_id, 'test')
         assert message.default_quote is True
+
+    @flaky(3, 1)
+    @pytest.mark.timeout(10)
+    def test_set_and_get_my_commands(self, bot):
+        commands = [
+            BotCommand('cmd1', 'descr1'),
+            BotCommand('cmd2', 'descr2'),
+        ]
+        bot.set_my_commands([])
+        assert bot.get_my_commands() == []
+        assert bot.commands == []
+        assert bot.set_my_commands(commands)
+
+        for bc in [bot.get_my_commands(), bot.commands]:
+            assert len(bc) == 2
+            assert bc[0].command == 'cmd1'
+            assert bc[0].description == 'descr1'
+            assert bc[1].command == 'cmd2'
+            assert bc[1].description == 'descr2'
+
+    @flaky(3, 1)
+    @pytest.mark.timeout(10)
+    def test_set_and_get_my_commands_strings(self, bot):
+        commands = [
+            ['cmd1', 'descr1'],
+            ['cmd2', 'descr2'],
+        ]
+        bot.set_my_commands([])
+        assert bot.get_my_commands() == []
+        assert bot.commands == []
+        assert bot.set_my_commands(commands)
+
+        for bc in [bot.get_my_commands(), bot.commands]:
+            assert len(bc) == 2
+            assert bc[0].command == 'cmd1'
+            assert bc[0].description == 'descr1'
+            assert bc[1].command == 'cmd2'
+            assert bc[1].description == 'descr2'

tests/test_botcommand.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2020
+# 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/].
+
+import pytest
+
+from telegram import BotCommand
+
+
+@pytest.fixture(scope="class")
+def bot_command():
+    return BotCommand(command='start', description='A command')
+
+
+class TestBotCommand(object):
+    command = 'start'
+    description = 'A command'
+
+    def test_de_json(self, bot):
+        json_dict = {'command': self.command, 'description': self.description}
+        bot_command = BotCommand.de_json(json_dict, bot)
+
+        assert bot_command.command == self.command
+        assert bot_command.description == self.description
+
+        assert BotCommand.de_json(None, bot) is None
+
+    def test_to_dict(self, bot_command):
+        bot_command_dict = bot_command.to_dict()
+
+        assert isinstance(bot_command_dict, dict)
+        assert bot_command_dict['command'] == bot_command.command
+        assert bot_command_dict['description'] == bot_command.description

tests/test_chatphoto.py

@@ -22,6 +22,7 @@ import pytest
 from flaky import flaky
 
 from telegram import ChatPhoto, Voice, TelegramError
+from tests.conftest import expect_bad_request
 
 
 @pytest.fixture(scope='function')
@@ -33,7 +34,10 @@ def chatphoto_file():
 
 @pytest.fixture(scope='function')
 def chat_photo(bot, super_group_id):
-    return bot.get_chat(super_group_id, timeout=50).photo
+    def func():
+        return bot.get_chat(super_group_id, timeout=50).photo
+
+    return expect_bad_request(func, 'Type of file mismatch', 'Telegram did not accept the file.')
 
 
 class TestChatPhoto(object):
@@ -46,7 +50,10 @@ class TestChatPhoto(object):
     @flaky(3, 1)
     @pytest.mark.timeout(10)
     def test_send_all_args(self, bot, super_group_id, chatphoto_file, chat_photo, thumb_file):
-        assert bot.set_chat_photo(super_group_id, chatphoto_file)
+        def func():
+            assert bot.set_chat_photo(super_group_id, chatphoto_file)
+
+        expect_bad_request(func, 'Type of file mismatch', 'Telegram did not accept the file.')
 
     @flaky(3, 1)
     @pytest.mark.timeout(10)

tests/test_commandhandler.py

@@ -379,6 +379,29 @@ class TestPrefixHandler(BaseTest):
         assert not is_match(handler, make_message_update('/test'))
         assert not mock_filter.tested
 
+    def test_edit_prefix(self):
+        handler = self.make_default_handler()
+        handler.prefix = ['?', '§']
+        assert handler._commands == list(combinations(['?', '§'], self.COMMANDS))
+        handler.prefix = '+'
+        assert handler._commands == list(combinations(['+'], self.COMMANDS))
+
+    def test_edit_command(self):
+        handler = self.make_default_handler()
+        handler.command = 'foo'
+        assert handler._commands == list(combinations(self.PREFIXES, ['foo']))
+
+    def test_basic_after_editing(self, dp, prefix, command):
+        """Test the basic expected response from a prefix handler"""
+        handler = self.make_default_handler()
+        dp.add_handler(handler)
+        text = prefix + command
+
+        assert self.response(dp, make_message_update(text))
+        handler.command = 'foo'
+        text = prefix + 'foo'
+        assert self.response(dp, make_message_update(text))
+
     def test_context(self, cdp, prefix_message_update):
         handler = self.make_default_handler(self.callback_context)
         cdp.add_handler(handler)

tests/test_conversationhandler.py

@@ -179,6 +179,38 @@ class TestConversationHandler(object):
         return self._set_state(update, self.STOPPING)
 
     # Tests
+    @pytest.mark.parametrize('attr', ['entry_points', 'states', 'fallbacks', 'per_chat', 'name',
+                             'per_user', 'allow_reentry', 'conversation_timeout', 'map_to_parent'],
+                             indirect=False)
+    def test_immutable(self, attr):
+        ch = ConversationHandler('entry_points', {'states': ['states']}, 'fallbacks',
+                                 per_chat='per_chat',
+                                 per_user='per_user', per_message=False,
+                                 allow_reentry='allow_reentry',
+                                 conversation_timeout='conversation_timeout',
+                                 name='name', map_to_parent='map_to_parent')
+
+        value = getattr(ch, attr)
+        if isinstance(value, list):
+            assert value[0] == attr
+        elif isinstance(value, dict):
+            assert list(value.keys())[0] == attr
+        else:
+            assert getattr(ch, attr) == attr
+        with pytest.raises(ValueError, match='You can not assign a new value to {}'.format(attr)):
+            setattr(ch, attr, True)
+
+    def test_immutable_per_message(self):
+        ch = ConversationHandler('entry_points', {'states': ['states']}, 'fallbacks',
+                                 per_chat='per_chat',
+                                 per_user='per_user', per_message=False,
+                                 allow_reentry='allow_reentry',
+                                 conversation_timeout='conversation_timeout',
+                                 name='name', map_to_parent='map_to_parent')
+        assert ch.per_message is False
+        with pytest.raises(ValueError, match='You can not assign a new value to per_message'):
+            ch.per_message = True
+
     def test_per_all_false(self):
         with pytest.raises(ValueError, match="can't all be 'False'"):
             ConversationHandler(self.entry_points, self.states, self.fallbacks,
@@ -514,6 +546,43 @@ class TestConversationHandler(object):
         dp.job_queue.tick()
         assert handler.conversations.get((self.group.id, user1.id)) is None
 
+    def test_conversation_handler_timeout_update_and_context(self, cdp, bot, user1):
+        context = None
+
+        def start_callback(u, c):
+            nonlocal context, self
+            context = c
+            return self.start(u, c)
+
+        states = self.states
+        timeout_handler = CommandHandler('start', None)
+        states.update({ConversationHandler.TIMEOUT: [timeout_handler]})
+        handler = ConversationHandler(entry_points=[CommandHandler('start', start_callback)],
+                                      states=states, fallbacks=self.fallbacks,
+                                      conversation_timeout=0.5)
+        cdp.add_handler(handler)
+
+        # Start state machine, then reach timeout
+        message = Message(0, user1, None, self.group, text='/start',
+                          entities=[MessageEntity(type=MessageEntity.BOT_COMMAND, offset=0,
+                                                  length=len('/start'))],
+                          bot=bot)
+        update = Update(update_id=0, message=message)
+
+        def timeout_callback(u, c):
+            nonlocal update, context, self
+            self.is_timeout = True
+            assert u is update
+            assert c is context
+
+        timeout_handler.callback = timeout_callback
+
+        cdp.process_update(update)
+        sleep(0.5)
+        cdp.job_queue.tick()
+        assert handler.conversations.get((self.group.id, user1.id)) is None
+        assert self.is_timeout
+
     def test_conversation_timeout_keeps_extending(self, dp, bot, user1):
         handler = ConversationHandler(entry_points=self.entry_points, states=self.states,
                                       fallbacks=self.fallbacks, conversation_timeout=0.5)

tests/test_dice.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2020
+# 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/].
+
+import pytest
+
+from telegram import Dice
+
+
+@pytest.fixture(scope="class",
+                params=Dice.ALL_EMOJI)
+def dice(request):
+    return Dice(value=5, emoji=request.param)
+
+
+class TestDice(object):
+    value = 4
+
+    @pytest.mark.parametrize('emoji', Dice.ALL_EMOJI)
+    def test_de_json(self, bot, emoji):
+        json_dict = {'value': self.value, 'emoji': emoji}
+        dice = Dice.de_json(json_dict, bot)
+
+        assert dice.value == self.value
+        assert dice.emoji == emoji
+        assert Dice.de_json(None, bot) is None
+
+    def test_to_dict(self, dice):
+        dice_dict = dice.to_dict()
+
+        assert isinstance(dice_dict, dict)
+        assert dice_dict['value'] == dice.value
+        assert dice_dict['emoji'] == dice.emoji

tests/test_dispatcher.py

@@ -373,6 +373,12 @@ class TestDispatcher(object):
             def update_user_data(self, user_id, data):
                 raise Exception
 
+            def get_conversations(self, name):
+                pass
+
+            def update_conversation(self, name, key, new_state):
+                pass
+
         def start1(b, u):
             pass
 
@@ -449,3 +455,118 @@ class TestDispatcher(object):
         with pytest.warns(TelegramDeprecationWarning):
             Dispatcher(dp.bot, dp.update_queue, job_queue=dp.job_queue, workers=0,
                        use_context=False)
+
+    def test_error_while_persisting(self, cdp, monkeypatch):
+        class OwnPersistence(BasePersistence):
+            def __init__(self):
+                super(OwnPersistence, self).__init__()
+                self.store_user_data = True
+                self.store_chat_data = True
+                self.store_bot_data = True
+
+            def update(self, data):
+                raise Exception('PersistenceError')
+
+            def update_bot_data(self, data):
+                self.update(data)
+
+            def update_chat_data(self, chat_id, data):
+                self.update(data)
+
+            def update_user_data(self, user_id, data):
+                self.update(data)
+
+            def get_chat_data(self):
+                pass
+
+            def get_bot_data(self):
+                pass
+
+            def get_user_data(self):
+                pass
+
+            def get_conversations(self, name):
+                pass
+
+            def update_conversation(self, name, key, new_state):
+                pass
+
+        def callback(update, context):
+            pass
+
+        test_flag = False
+
+        def error(update, context):
+            nonlocal test_flag
+            test_flag = str(context.error) == 'PersistenceError'
+            raise Exception('ErrorHandlingError')
+
+        def logger(message):
+            assert 'uncaught error was raised while handling' in message
+
+        update = Update(1, message=Message(1, User(1, '', False), None, Chat(1, ''), text='Text'))
+        handler = MessageHandler(Filters.all, callback)
+        cdp.add_handler(handler)
+        cdp.add_error_handler(error)
+        monkeypatch.setattr(cdp.logger, 'exception', logger)
+
+        cdp.persistence = OwnPersistence()
+        cdp.process_update(update)
+        assert test_flag
+
+    def test_persisting_no_user_no_chat(self, cdp):
+        class OwnPersistence(BasePersistence):
+            def __init__(self):
+                super(OwnPersistence, self).__init__()
+                self.store_user_data = True
+                self.store_chat_data = True
+                self.store_bot_data = True
+                self.test_flag_bot_data = False
+                self.test_flag_chat_data = False
+                self.test_flag_user_data = False
+
+            def update_bot_data(self, data):
+                self.test_flag_bot_data = True
+
+            def update_chat_data(self, chat_id, data):
+                self.test_flag_chat_data = True
+
+            def update_user_data(self, user_id, data):
+                self.test_flag_user_data = True
+
+            def update_conversation(self, name, key, new_state):
+                pass
+
+            def get_conversations(self, name):
+                pass
+
+            def get_user_data(self):
+                pass
+
+            def get_bot_data(self):
+                pass
+
+            def get_chat_data(self):
+                pass
+
+        def callback(update, context):
+            pass
+
+        handler = MessageHandler(Filters.all, callback)
+        cdp.add_handler(handler)
+        cdp.persistence = OwnPersistence()
+
+        update = Update(1, message=Message(1, User(1, '', False), None, None, text='Text'))
+        cdp.process_update(update)
+        assert cdp.persistence.test_flag_bot_data
+        assert cdp.persistence.test_flag_user_data
+        assert not cdp.persistence.test_flag_chat_data
+
+        cdp.persistence.test_flag_bot_data = False
+        cdp.persistence.test_flag_user_data = False
+        cdp.persistence.test_flag_chat_data = False
+        update = Update(1, message=Message(1, None, None, Chat(1, ''), text='Text'))
+        cdp.process_update(update)
+        assert cdp.persistence.test_flag_bot_data
+        assert not cdp.persistence.test_flag_user_data
+        assert cdp.persistence.test_flag_chat_data

tests/test_filters.py

@@ -20,7 +20,7 @@ import datetime
 
 import pytest
 
-from telegram import Message, User, Chat, MessageEntity, Document, Update
+from telegram import Message, User, Chat, MessageEntity, Document, Update, Dice
 from telegram.ext import Filters, BaseFilter
 import re
 
@@ -47,7 +47,7 @@ class TestFilters(object):
         update.message.text = '/test'
         assert (Filters.text)(update)
 
-    def test_filters_text_iterable(self, update):
+    def test_filters_text_strings(self, update):
         update.message.text = '/test'
         assert Filters.text({'/test', 'test1'})(update)
         assert not Filters.text(['test1', 'test2'])(update)
@@ -58,7 +58,7 @@ class TestFilters(object):
         update.message.caption = None
         assert not (Filters.caption)(update)
 
-    def test_filters_caption_iterable(self, update):
+    def test_filters_caption_strings(self, update):
         update.message.caption = 'test'
         assert Filters.caption({'test', 'test1'})(update)
         assert not Filters.caption(['test1', 'test2'])(update)
@@ -622,6 +622,37 @@ class TestFilters(object):
         update.message.poll = 'test'
         assert Filters.poll(update)
 
+    @pytest.mark.parametrize('emoji', Dice.ALL_EMOJI)
+    def test_filters_dice(self, update, emoji):
+        update.message.dice = Dice(4, emoji)
+        assert Filters.dice(update)
+        update.message.dice = None
+        assert not Filters.dice(update)
+
+    @pytest.mark.parametrize('emoji', Dice.ALL_EMOJI)
+    def test_filters_dice_list(self, update, emoji):
+        update.message.dice = None
+        assert not Filters.dice(5)(update)
+
+        update.message.dice = Dice(5, emoji)
+        assert Filters.dice(5)(update)
+        assert Filters.dice({5, 6})(update)
+        assert not Filters.dice(1)(update)
+        assert not Filters.dice([2, 3])(update)
+
+    def test_filters_dice_type(self, update):
+        update.message.dice = Dice(5, '🎲')
+        assert Filters.dice.dice(update)
+        assert Filters.dice.dice([4, 5])(update)
+        assert not Filters.dice.darts(update)
+        assert not Filters.dice.dice([6])(update)
+
+        update.message.dice = Dice(5, '🎯')
+        assert Filters.dice.darts(update)
+        assert Filters.dice.darts([4, 5])(update)
+        assert not Filters.dice.dice(update)
+        assert not Filters.dice.darts([6])(update)
+
     def test_language_filter_single(self, update):
         update.message.from_user.language_code = 'en_US'
         assert (Filters.language('en_US'))(update)
@@ -714,10 +745,8 @@ class TestFilters(object):
         class _CustomFilter(BaseFilter):
             pass
 
-        custom = _CustomFilter()
-
-        with pytest.raises(NotImplementedError):
-            (custom & Filters.text)(update)
+        with pytest.raises(TypeError, match='Can\'t instantiate abstract class _CustomFilter'):
+            _CustomFilter()
 
     def test_custom_unnamed_filter(self, update):
         class Unnamed(BaseFilter):

tests/test_helpers.py

@@ -27,14 +27,14 @@ from telegram import User
 from telegram import MessageEntity
 from telegram.message import Message
 from telegram.utils import helpers
-from telegram.utils.helpers import _UtcOffsetTimezone, _datetime_to_float_timestamp
+from telegram.utils.helpers import _datetime_to_float_timestamp
 
 
 # sample time specification values categorised into absolute / delta / time-of-day
-ABSOLUTE_TIME_SPECS = [dtm.datetime.now(tz=_UtcOffsetTimezone(dtm.timedelta(hours=-7))),
+ABSOLUTE_TIME_SPECS = [dtm.datetime.now(tz=dtm.timezone(dtm.timedelta(hours=-7))),
                        dtm.datetime.utcnow()]
 DELTA_TIME_SPECS = [dtm.timedelta(hours=3, seconds=42, milliseconds=2), 30, 7.5]
-TIME_OF_DAY_TIME_SPECS = [dtm.time(12, 42, tzinfo=_UtcOffsetTimezone(dtm.timedelta(hours=-7))),
+TIME_OF_DAY_TIME_SPECS = [dtm.time(12, 42, tzinfo=dtm.timezone(dtm.timedelta(hours=-7))),
                           dtm.time(12, 42)]
 RELATIVE_TIME_SPECS = DELTA_TIME_SPECS + TIME_OF_DAY_TIME_SPECS
 TIME_SPECS = ABSOLUTE_TIME_SPECS + RELATIVE_TIME_SPECS
@@ -142,8 +142,16 @@ class TestHelpers(object):
         # this 'convenience' behaviour has been left left for backwards compatibility
         assert helpers.to_timestamp(None) is None
 
-    def test_from_timestamp(self):
-        assert helpers.from_timestamp(1573431976) == dtm.datetime(2019, 11, 11, 0, 26, 16)
+    def test_from_timestamp_naive(self):
+        datetime = dtm.datetime(2019, 11, 11, 0, 26, 16, tzinfo=None)
+        assert helpers.from_timestamp(1573431976, tzinfo=None) == datetime
+
+    def test_from_timestamp_aware(self, timezone):
+        # we're parametrizing this with two different UTC offsets to exclude the possibility
+        # of an xpass when the test is run in a timezone with the same UTC offset
+        datetime = dtm.datetime(2019, 11, 11, 0, 26, 16, 10**5, tzinfo=timezone)
+        assert (helpers.from_timestamp(1573431976.1 - timezone.utcoffset(None).total_seconds())
+                == datetime)
 
     def test_create_deep_linked_url(self):
         username = 'JamesTheMock'

tests/test_inlinekeyboardmarkup.py

@@ -20,7 +20,7 @@
 import pytest
 from flaky import flaky
 
-from telegram import InlineKeyboardButton, InlineKeyboardMarkup
+from telegram import InlineKeyboardButton, InlineKeyboardMarkup, ReplyMarkup
 
 
 @pytest.fixture(scope='class')
@@ -68,6 +68,26 @@ class TestInlineKeyboardMarkup(object):
     def test_expected_values(self, inline_keyboard_markup):
         assert inline_keyboard_markup.inline_keyboard == self.inline_keyboard
 
+    def test_expected_values_empty_switch(self, inline_keyboard_markup, bot, monkeypatch):
+        def test(url, data, reply_to_message_id=None, disable_notification=None,
+                 reply_markup=None, timeout=None, **kwargs):
+            if reply_markup is not None:
+                if isinstance(reply_markup, ReplyMarkup):
+                    data['reply_markup'] = reply_markup.to_json()
+                else:
+                    data['reply_markup'] = reply_markup
+
+            assert bool('"switch_inline_query": ""' in data['reply_markup'])
+            assert bool('"switch_inline_query_current_chat": ""' in data['reply_markup'])
+
+        inline_keyboard_markup.inline_keyboard[0][0].callback_data = None
+        inline_keyboard_markup.inline_keyboard[0][0].switch_inline_query = ''
+        inline_keyboard_markup.inline_keyboard[0][1].callback_data = None
+        inline_keyboard_markup.inline_keyboard[0][1].switch_inline_query_current_chat = ''
+
+        monkeypatch.setattr(bot, '_message', test)
+        bot.send_message(123, 'test', reply_markup=inline_keyboard_markup)
+
     def test_to_dict(self, inline_keyboard_markup):
         inline_keyboard_markup_dict = inline_keyboard_markup.to_dict()
 

tests/test_inputmedia.py

@@ -31,6 +31,7 @@ from .test_document import document, document_file  # noqa: F401
 from .test_photo import _photo, photo_file, photo, thumb  # noqa: F401
 # noinspection PyUnresolvedReferences
 from .test_video import video, video_file  # noqa: F401
+from tests.conftest import expect_bad_request
 
 
 @pytest.fixture(scope='class')
@@ -320,10 +321,14 @@ class TestSendMediaGroup(object):
     @pytest.mark.timeout(10)  # noqa: F811
     def test_send_media_group_new_files(self, bot, chat_id, video_file, photo_file,  # noqa: F811
                                         animation_file):  # noqa: F811
-        messages = bot.send_media_group(chat_id, [
-            InputMediaVideo(video_file),
-            InputMediaPhoto(photo_file)
-        ])
+        def func():
+            return bot.send_media_group(chat_id, [
+                InputMediaVideo(video_file),
+                InputMediaPhoto(photo_file)
+            ])
+        messages = expect_bad_request(func, 'Type of file mismatch',
+                                      'Telegram did not accept the file.')
+
         assert isinstance(messages, list)
         assert len(messages) == 2
         assert all([isinstance(mes, Message) for mes in messages])

tests/test_jobqueue.py

@@ -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/].
+import calendar
 import datetime as dtm
 import os
 import sys
@@ -25,10 +26,8 @@ from time import sleep
 
 import pytest
 from flaky import flaky
-
 from telegram.ext import JobQueue, Updater, Job, CallbackContext
 from telegram.utils.deprecate import TelegramDeprecationWarning
-from telegram.utils.helpers import _UtcOffsetTimezone
 
 
 @pytest.fixture(scope='function')
@@ -276,7 +275,7 @@ class TestJobQueue(object):
         # must subtract one minute because the UTC offset has to be strictly less than 24h
         # thus this test will xpass if run in the interval [00:00, 00:01) UTC time
         # (because target time will be 23:59 UTC, so local and target weekday will be the same)
-        target_tzinfo = _UtcOffsetTimezone(dtm.timedelta(days=1, minutes=-1))
+        target_tzinfo = dtm.timezone(dtm.timedelta(days=1, minutes=-1))
         target_datetime = (utcnow + dtm.timedelta(days=1, minutes=-1, seconds=delta)).replace(
             tzinfo=target_tzinfo)
         target_time = target_datetime.timetz()
@@ -288,6 +287,69 @@ class TestJobQueue(object):
         assert self.result == 1
         assert job_queue._queue.get(False)[0] == pytest.approx(expected_reschedule_time)
 
+    def test_run_monthly(self, job_queue):
+        delta, now = 0.1, time.time()
+        date_time = dtm.datetime.utcfromtimestamp(now)
+        time_of_day = (date_time + dtm.timedelta(seconds=delta)).time()
+        expected_reschedule_time = now + delta
+
+        day = date_time.day
+        expected_reschedule_time += calendar.monthrange(date_time.year,
+                                                        date_time.month)[1] * 24 * 60 * 60
+
+        job_queue.run_monthly(self.job_run_once, time_of_day, day)
+        sleep(0.2)
+        assert self.result == 1
+        assert job_queue._queue.get(False)[0] == pytest.approx(expected_reschedule_time)
+
+    def test_run_monthly_and_not_strict(self, job_queue):
+        # This only really tests something in months with < 31 days.
+        # But the trouble of patching datetime is probably not worth it
+
+        delta, now = 0.1, time.time()
+        date_time = dtm.datetime.utcfromtimestamp(now)
+        time_of_day = (date_time + dtm.timedelta(seconds=delta)).time()
+        expected_reschedule_time = now + delta
+
+        day = date_time.day
+        date_time += dtm.timedelta(calendar.monthrange(date_time.year,
+                                                       date_time.month)[1] - day)
+        # next job should be scheduled on last day of month if day_is_strict is False
+        expected_reschedule_time += (calendar.monthrange(date_time.year,
+                                                         date_time.month)[1] - day) * 24 * 60 * 60
+
+        job_queue.run_monthly(self.job_run_once, time_of_day, 31, day_is_strict=False)
+        assert job_queue._queue.get(False)[0] == pytest.approx(expected_reschedule_time)
+
+    def test_run_monthly_with_timezone(self, job_queue):
+        """test that the day is retrieved based on the job's timezone
+        We set a job to run at the current UTC time of day (plus a small delay buffer) with a
+        timezone that is---approximately (see below)---UTC +24, and set it to run on the weekday
+        after the current UTC weekday. The job should therefore be executed now (because in UTC+24,
+        the time of day is the same as the current weekday is the one after the current UTC
+        weekday).
+        """
+        now = time.time()
+        utcnow = dtm.datetime.utcfromtimestamp(now)
+        delta = 0.1
+
+        # must subtract one minute because the UTC offset has to be strictly less than 24h
+        # thus this test will xpass if run in the interval [00:00, 00:01) UTC time
+        # (because target time will be 23:59 UTC, so local and target weekday will be the same)
+        target_tzinfo = dtm.timezone(dtm.timedelta(days=1, minutes=-1))
+        target_datetime = (utcnow + dtm.timedelta(days=1, minutes=-1, seconds=delta)).replace(
+            tzinfo=target_tzinfo)
+        target_time = target_datetime.timetz()
+        target_day = target_datetime.day
+        expected_reschedule_time = now + delta
+        expected_reschedule_time += calendar.monthrange(target_datetime.year,
+                                                        target_datetime.month)[1] * 24 * 60 * 60
+
+        job_queue.run_monthly(self.job_run_once, target_time, target_day)
+        sleep(delta + 0.1)
+        assert self.result == 1
+        assert job_queue._queue.get(False)[0] == pytest.approx(expected_reschedule_time)
+
     def test_warnings(self, job_queue):
         j = Job(self.job_run_once, repeat=False)
         with pytest.raises(ValueError, match='can not be set to'):
@@ -298,18 +360,21 @@ class TestJobQueue(object):
         with pytest.raises(ValueError, match='can not be'):
             j.interval = None
         j.repeat = False
-        with pytest.raises(ValueError, match='must be of type'):
+        with pytest.raises(TypeError, match='must be of type'):
             j.interval = 'every 3 minutes'
         j.interval = 15
         assert j.interval_seconds == 15
 
-        with pytest.raises(ValueError, match='argument should be of type'):
+        with pytest.raises(TypeError, match='argument should be of type'):
             j.days = 'every day'
-        with pytest.raises(ValueError, match='The elements of the'):
+        with pytest.raises(TypeError, match='The elements of the'):
             j.days = ('mon', 'wed')
         with pytest.raises(ValueError, match='from 0 up to and'):
             j.days = (0, 6, 12, 14)
 
+        with pytest.raises(TypeError, match='argument should be one of the'):
+            j._set_next_t('tomorrow')
+
     def test_get_jobs(self, job_queue):
         job1 = job_queue.run_once(self.job_run_once, 10, name='name1')
         job2 = job_queue.run_once(self.job_run_once, 10, name='name1')
@@ -330,3 +395,111 @@ class TestJobQueue(object):
         sleep(0.03)
 
         assert self.result == 0
+
+    def test_job_default_tzinfo(self, job_queue):
+        """Test that default tzinfo is always set to UTC"""
+        job_1 = job_queue.run_once(self.job_run_once, 0.01)
+        job_2 = job_queue.run_repeating(self.job_run_once, 10)
+        job_3 = job_queue.run_daily(self.job_run_once, time=dtm.time(hour=15))
+
+        jobs = [job_1, job_2, job_3]
+
+        for job in jobs:
+            assert job.tzinfo == dtm.timezone.utc
+
+    def test_job_next_t_property(self, job_queue):
+        # Testing:
+        # - next_t values match values from self._queue.queue (for run_once and run_repeating jobs)
+        # - next_t equals None if job is removed or if it's already ran
+
+        job1 = job_queue.run_once(self.job_run_once, 0.06, name='run_once job')
+        job2 = job_queue.run_once(self.job_run_once, 0.06, name='canceled run_once job')
+        job_queue.run_repeating(self.job_run_once, 0.04, name='repeatable job')
+
+        sleep(0.05)
+        job2.schedule_removal()
+
+        with job_queue._queue.mutex:
+            for t, job in job_queue._queue.queue:
+                t = dtm.datetime.fromtimestamp(t, job.tzinfo)
+
+                if job.removed:
+                    assert job.next_t is None
+                else:
+                    assert job.next_t == t
+
+        assert self.result == 1
+        sleep(0.02)
+
+        assert self.result == 2
+        assert job1.next_t is None
+        assert job2.next_t is None
+
+    def test_job_set_next_t(self, job_queue):
+        # Testing next_t setter for 'datetime.datetime' values
+
+        job = job_queue.run_once(self.job_run_once, 0.05)
+
+        t = dtm.datetime.now(tz=dtm.timezone(dtm.timedelta(hours=12)))
+        job._set_next_t(t)
+        job.tzinfo = dtm.timezone(dtm.timedelta(hours=5))
+        assert job.next_t == t.astimezone(job.tzinfo)
+
+    def test_passing_tzinfo_to_job(self, job_queue):
+        """Test that tzinfo is correctly passed to job with run_once, run_daily, run_repeating
+        and run_monthly methods"""
+
+        when_dt_tz_specific = dtm.datetime.now(
+            tz=dtm.timezone(dtm.timedelta(hours=12))
+        ) + dtm.timedelta(seconds=2)
+        when_dt_tz_utc = dtm.datetime.now() + dtm.timedelta(seconds=2)
+        job_once1 = job_queue.run_once(self.job_run_once, when_dt_tz_specific)
+        job_once2 = job_queue.run_once(self.job_run_once, when_dt_tz_utc)
+
+        when_time_tz_specific = (dtm.datetime.now(
+            tz=dtm.timezone(dtm.timedelta(hours=12))
+        ) + dtm.timedelta(seconds=2)).timetz()
+        when_time_tz_utc = (dtm.datetime.now() + dtm.timedelta(seconds=2)).timetz()
+        job_once3 = job_queue.run_once(self.job_run_once, when_time_tz_specific)
+        job_once4 = job_queue.run_once(self.job_run_once, when_time_tz_utc)
+
+        first_dt_tz_specific = dtm.datetime.now(
+            tz=dtm.timezone(dtm.timedelta(hours=12))
+        ) + dtm.timedelta(seconds=2)
+        first_dt_tz_utc = dtm.datetime.now() + dtm.timedelta(seconds=2)
+        job_repeating1 = job_queue.run_repeating(
+            self.job_run_once, 2, first=first_dt_tz_specific)
+        job_repeating2 = job_queue.run_repeating(
+            self.job_run_once, 2, first=first_dt_tz_utc)
+
+        first_time_tz_specific = (dtm.datetime.now(
+            tz=dtm.timezone(dtm.timedelta(hours=12))
+        ) + dtm.timedelta(seconds=2)).timetz()
+        first_time_tz_utc = (dtm.datetime.now() + dtm.timedelta(seconds=2)).timetz()
+        job_repeating3 = job_queue.run_repeating(
+            self.job_run_once, 2, first=first_time_tz_specific)
+        job_repeating4 = job_queue.run_repeating(
+            self.job_run_once, 2, first=first_time_tz_utc)
+
+        time_tz_specific = (dtm.datetime.now(
+            tz=dtm.timezone(dtm.timedelta(hours=12))
+        ) + dtm.timedelta(seconds=2)).timetz()
+        time_tz_utc = (dtm.datetime.now() + dtm.timedelta(seconds=2)).timetz()
+        job_daily1 = job_queue.run_daily(self.job_run_once, time_tz_specific)
+        job_daily2 = job_queue.run_daily(self.job_run_once, time_tz_utc)
+
+        job_monthly1 = job_queue.run_monthly(self.job_run_once, time_tz_specific, 1)
+        job_monthly2 = job_queue.run_monthly(self.job_run_once, time_tz_utc, 1)
+
+        assert job_once1.tzinfo == when_dt_tz_specific.tzinfo
+        assert job_once2.tzinfo == dtm.timezone.utc
+        assert job_once3.tzinfo == when_time_tz_specific.tzinfo
+        assert job_once4.tzinfo == dtm.timezone.utc
+        assert job_repeating1.tzinfo == first_dt_tz_specific.tzinfo
+        assert job_repeating2.tzinfo == dtm.timezone.utc
+        assert job_repeating3.tzinfo == first_time_tz_specific.tzinfo
+        assert job_repeating4.tzinfo == dtm.timezone.utc
+        assert job_daily1.tzinfo == time_tz_specific.tzinfo
+        assert job_daily2.tzinfo == dtm.timezone.utc
+        assert job_monthly1.tzinfo == time_tz_specific.tzinfo
+        assert job_monthly2.tzinfo == dtm.timezone.utc

tests/test_message.py

@@ -22,7 +22,7 @@ import pytest
 
 from telegram import (Update, Message, User, MessageEntity, Chat, Audio, Document, Animation,
                       Game, PhotoSize, Sticker, Video, Voice, VideoNote, Contact, Location, Venue,
-                      Invoice, SuccessfulPayment, PassportData, ParseMode, Poll, PollOption)
+                      Invoice, SuccessfulPayment, PassportData, ParseMode, Poll, PollOption, Dice)
 from tests.test_passport import RAW_PASSPORT_DATA
 
 
@@ -92,12 +92,13 @@ def message(bot):
                                   options=[PollOption(text='a', voter_count=1),
                                            PollOption(text='b', voter_count=2)], is_closed=False,
                                   total_voter_count=0, is_anonymous=False, type=Poll.REGULAR,
-                                  allows_multiple_answers=True)},
+                                  allows_multiple_answers=True, explanation_entities=[])},
                     {'text': 'a text message', 'reply_markup': {'inline_keyboard': [[{
                         'text': 'start', 'url': 'http://google.com'}, {
                         'text': 'next', 'callback_data': 'abcd'}],
                         [{'text': 'Cancel', 'callback_data': 'Cancel'}]]}},
-                    {'quote': True}
+                    {'quote': True},
+                    {'dice': Dice(4, '🎲')}
                 ],
                 ids=['forwarded_user', 'forwarded_channel', 'reply', 'edited', 'text',
                      'caption_entities', 'audio', 'document', 'animation', 'game', 'photo',
@@ -107,7 +108,7 @@ def message(bot):
                      'migrated_from', 'pinned', 'invoice', 'successful_payment',
                      'connected_website', 'forward_signature', 'author_signature',
                      'photo_from_media_group', 'passport_data', 'poll', 'reply_markup',
-                     'default_quote'])
+                     'default_quote', 'dice'])
 def message_params(bot, request):
     return Message(message_id=TestMessage.id_,
                    from_user=TestMessage.from_user,
@@ -702,7 +703,7 @@ class TestMessage(object):
     def test_reply_poll(self, monkeypatch, message):
         def test(*args, **kwargs):
             id_ = args[0] == message.chat_id
-            contact = kwargs['contact'] == 'test_poll'
+            contact = kwargs['question'] == 'test_poll'
             if kwargs.get('reply_to_message_id'):
                 reply = kwargs['reply_to_message_id'] == message.message_id
             else:
@@ -710,8 +711,22 @@ class TestMessage(object):
             return id_ and contact and reply
 
         monkeypatch.setattr(message.bot, 'send_poll', test)
-        assert message.reply_poll(contact='test_poll')
-        assert message.reply_poll(contact='test_poll', quote=True)
+        assert message.reply_poll(question='test_poll')
+        assert message.reply_poll(question='test_poll', quote=True)
+
+    def test_reply_dice(self, monkeypatch, message):
+        def test(*args, **kwargs):
+            id_ = args[0] == message.chat_id
+            contact = kwargs['disable_notification'] is True
+            if kwargs.get('reply_to_message_id'):
+                reply = kwargs['reply_to_message_id'] == message.message_id
+            else:
+                reply = True
+            return id_ and contact and reply
+
+        monkeypatch.setattr(message.bot, 'send_dice', test)
+        assert message.reply_dice(disable_notification=True)
+        assert message.reply_dice(disable_notification=True, quote=True)
 
     def test_forward(self, monkeypatch, message):
         def test(*args, **kwargs):

tests/test_persistence.py

@@ -29,12 +29,13 @@ import logging
 import os
 import pickle
 from collections import defaultdict
+from time import sleep
 
 import pytest
 
 from telegram import Update, Message, User, Chat, MessageEntity
 from telegram.ext import BasePersistence, Updater, ConversationHandler, MessageHandler, Filters, \
-    PicklePersistence, CommandHandler, DictPersistence, TypeHandler
+    PicklePersistence, CommandHandler, DictPersistence, TypeHandler, JobQueue
 
 
 @pytest.fixture(autouse=True)
@@ -50,7 +51,33 @@ def change_directory(tmp_path):
 
 @pytest.fixture(scope="function")
 def base_persistence():
-    return BasePersistence(store_chat_data=True, store_user_data=True, store_bot_data=True)
+    class OwnPersistence(BasePersistence):
+
+        def get_bot_data(self):
+            raise NotImplementedError
+
+        def get_chat_data(self):
+            raise NotImplementedError
+
+        def get_user_data(self):
+            raise NotImplementedError
+
+        def get_conversations(self, name):
+            raise NotImplementedError
+
+        def update_bot_data(self, data):
+            raise NotImplementedError
+
+        def update_chat_data(self, chat_id, data):
+            raise NotImplementedError
+
+        def update_conversation(self, name, key, new_state):
+            raise NotImplementedError
+
+        def update_user_data(self, user_id, data):
+            raise NotImplementedError
+
+    return OwnPersistence(store_chat_data=True, store_user_data=True, store_bot_data=True)
 
 
 @pytest.fixture(scope="function")
@@ -87,27 +114,25 @@ def updater(bot, base_persistence):
     return u
 
 
+@pytest.fixture(scope='function')
+def job_queue(bot):
+    jq = JobQueue()
+    yield jq
+    jq.stop()
+
+
 class TestBasePersistence(object):
 
     def test_creation(self, base_persistence):
         assert base_persistence.store_chat_data
         assert base_persistence.store_user_data
-        with pytest.raises(NotImplementedError):
-            base_persistence.get_bot_data()
-        with pytest.raises(NotImplementedError):
-            base_persistence.get_chat_data()
-        with pytest.raises(NotImplementedError):
-            base_persistence.get_user_data()
-        with pytest.raises(NotImplementedError):
-            base_persistence.get_conversations("test")
-        with pytest.raises(NotImplementedError):
-            base_persistence.update_bot_data(None)
-        with pytest.raises(NotImplementedError):
-            base_persistence.update_chat_data(None, None)
-        with pytest.raises(NotImplementedError):
-            base_persistence.update_user_data(None, None)
-        with pytest.raises(NotImplementedError):
-            base_persistence.update_conversation(None, None, None)
+        assert base_persistence.store_bot_data
+
+    def test_abstract_methods(self):
+        with pytest.raises(TypeError, match=('get_bot_data, get_chat_data, get_conversations, '
+                                             'get_user_data, update_bot_data, update_chat_data, '
+                                             'update_conversation, update_user_data')):
+            BasePersistence()
 
     def test_implementation(self, updater, base_persistence):
         dp = updater.dispatcher
@@ -119,8 +144,6 @@ class TestBasePersistence(object):
         with pytest.raises(ValueError, match="if dispatcher has no persistence"):
             dp.add_handler(ConversationHandler([], {}, [], persistent=True, name="My Handler"))
         dp.persistence = base_persistence
-        with pytest.raises(NotImplementedError):
-            dp.add_handler(ConversationHandler([], {}, [], persistent=True, name="My Handler"))
 
     def test_dispatcher_integration_init(self, bot, base_persistence, chat_data, user_data,
                                          bot_data):
@@ -920,6 +943,24 @@ class TestPickelPersistence(object):
         assert nested_ch.conversations[nested_ch._get_key(update)] == 1
         assert nested_ch.conversations == pickle_persistence.conversations['name3']
 
+    def test_with_job(self, job_queue, cdp, pickle_persistence):
+        def job_callback(context):
+            context.bot_data['test1'] = '456'
+            context.dispatcher.chat_data[123]['test2'] = '789'
+            context.dispatcher.user_data[789]['test3'] = '123'
+
+        cdp.persistence = pickle_persistence
+        job_queue.set_dispatcher(cdp)
+        job_queue.start()
+        job_queue.run_once(job_callback, 0.01)
+        sleep(0.05)
+        bot_data = pickle_persistence.get_bot_data()
+        assert bot_data == {'test1': '456'}
+        chat_data = pickle_persistence.get_chat_data()
+        assert chat_data[123] == {'test2': '789'}
+        user_data = pickle_persistence.get_user_data()
+        assert user_data[789] == {'test3': '123'}
+
 
 @pytest.fixture(scope='function')
 def user_data_json(user_data):
@@ -1202,3 +1243,22 @@ class TestDictPersistence(object):
         assert ch.conversations == dict_persistence.conversations['name2']
         assert nested_ch.conversations[nested_ch._get_key(update)] == 1
         assert nested_ch.conversations == dict_persistence.conversations['name3']
+
+    def test_with_job(self, job_queue, cdp):
+        def job_callback(context):
+            context.bot_data['test1'] = '456'
+            context.dispatcher.chat_data[123]['test2'] = '789'
+            context.dispatcher.user_data[789]['test3'] = '123'
+
+        dict_persistence = DictPersistence()
+        cdp.persistence = dict_persistence
+        job_queue.set_dispatcher(cdp)
+        job_queue.start()
+        job_queue.run_once(job_callback, 0.01)
+        sleep(0.05)
+        bot_data = dict_persistence.get_bot_data()
+        assert bot_data == {'test1': '456'}
+        chat_data = dict_persistence.get_chat_data()
+        assert chat_data[123] == {'test2': '789'}
+        user_data = dict_persistence.get_user_data()
+        assert user_data[789] == {'test3': '123'}

tests/test_photo.py

@@ -24,6 +24,7 @@ from flaky import flaky
 
 from telegram import Sticker, TelegramError, PhotoSize, InputFile
 from telegram.utils.helpers import escape_markdown
+from tests.conftest import expect_bad_request
 
 
 @pytest.fixture(scope='function')
@@ -35,8 +36,11 @@ def photo_file():
 
 @pytest.fixture(scope='class')
 def _photo(bot, chat_id):
-    with open('tests/data/telegram.jpg', 'rb') as f:
-        return bot.send_photo(chat_id, photo=f, timeout=50).photo
+    def func():
+        with open('tests/data/telegram.jpg', 'rb') as f:
+            return bot.send_photo(chat_id, photo=f, timeout=50).photo
+
+    return expect_bad_request(func, 'Type of file mismatch', 'Telegram did not accept the file.')
 
 
 @pytest.fixture(scope='class')

tests/test_poll.py

@@ -19,7 +19,9 @@
 
 import pytest
 
-from telegram import Poll, PollOption, PollAnswer, User
+from datetime import datetime
+from telegram import Poll, PollOption, PollAnswer, User, MessageEntity
+from telegram.utils.helpers import to_timestamp
 
 
 @pytest.fixture(scope="class")
@@ -91,7 +93,11 @@ def poll():
                 TestPoll.is_closed,
                 TestPoll.is_anonymous,
                 TestPoll.type,
-                TestPoll.allows_multiple_answers
+                TestPoll.allows_multiple_answers,
+                explanation=TestPoll.explanation,
+                explanation_entities=TestPoll.explanation_entities,
+                open_period=TestPoll.open_period,
+                close_date=TestPoll.close_date,
                 )
 
 
@@ -104,6 +110,11 @@ class TestPoll(object):
     is_anonymous = False
     type = Poll.REGULAR
     allows_multiple_answers = True
+    explanation = (b'\\U0001f469\\u200d\\U0001f469\\u200d\\U0001f467'
+                   b'\\u200d\\U0001f467\\U0001f431http://google.com').decode('unicode-escape')
+    explanation_entities = [MessageEntity(13, 17, MessageEntity.URL)]
+    open_period = 42
+    close_date = datetime.utcnow()
 
     def test_de_json(self):
         json_dict = {
@@ -114,7 +125,11 @@ class TestPoll(object):
             'is_closed': self.is_closed,
             'is_anonymous': self.is_anonymous,
             'type': self.type,
-            'allows_multiple_answers': self.allows_multiple_answers
+            'allows_multiple_answers': self.allows_multiple_answers,
+            'explanation': self.explanation,
+            'explanation_entities': [self.explanation_entities[0].to_dict()],
+            'open_period': self.open_period,
+            'close_date': to_timestamp(self.close_date)
         }
         poll = Poll.de_json(json_dict, None)
 
@@ -130,6 +145,11 @@ class TestPoll(object):
         assert poll.is_anonymous == self.is_anonymous
         assert poll.type == self.type
         assert poll.allows_multiple_answers == self.allows_multiple_answers
+        assert poll.explanation == self.explanation
+        assert poll.explanation_entities == self.explanation_entities
+        assert poll.open_period == self.open_period
+        assert pytest.approx(poll.close_date == self.close_date)
+        assert to_timestamp(poll.close_date) == to_timestamp(self.close_date)
 
     def test_to_dict(self, poll):
         poll_dict = poll.to_dict()
@@ -143,3 +163,21 @@ class TestPoll(object):
         assert poll_dict['is_anonymous'] == poll.is_anonymous
         assert poll_dict['type'] == poll.type
         assert poll_dict['allows_multiple_answers'] == poll.allows_multiple_answers
+        assert poll_dict['explanation'] == poll.explanation
+        assert poll_dict['explanation_entities'] == [poll.explanation_entities[0].to_dict()]
+        assert poll_dict['open_period'] == poll.open_period
+        assert poll_dict['close_date'] == to_timestamp(poll.close_date)
+
+    def test_parse_entity(self, poll):
+        entity = MessageEntity(type=MessageEntity.URL, offset=13, length=17)
+        poll.explanation_entities = [entity]
+
+        assert poll.parse_explanation_entity(entity) == 'http://google.com'
+
+    def test_parse_entities(self, poll):
+        entity = MessageEntity(type=MessageEntity.URL, offset=13, length=17)
+        entity_2 = MessageEntity(type=MessageEntity.BOLD, offset=13, length=1)
+        poll.explanation_entities = [entity_2, entity]
+
+        assert poll.parse_explanation_entities(MessageEntity.URL) == {entity: 'http://google.com'}
+        assert poll.parse_explanation_entities() == {entity: 'http://google.com', entity_2: 'h'}

tests/test_sticker.py

@@ -25,6 +25,7 @@ from flaky import flaky
 from future.utils import PY2
 
 from telegram import Sticker, PhotoSize, TelegramError, StickerSet, Audio, MaskPosition
+from telegram.error import BadRequest
 
 
 @pytest.fixture(scope='function')
@@ -40,6 +41,19 @@ def sticker(bot, chat_id):
         return bot.send_sticker(chat_id, sticker=f, timeout=50).sticker
 
 
+@pytest.fixture(scope='function')
+def animated_sticker_file():
+    f = open('tests/data/telegram_animated_sticker.tgs', 'rb')
+    yield f
+    f.close()
+
+
+@pytest.fixture(scope='class')
+def animated_sticker(bot, chat_id):
+    with open('tests/data/telegram_animated_sticker.tgs', 'rb') as f:
+        return bot.send_sticker(chat_id, sticker=f, timeout=50).sticker
+
+
 class TestSticker(object):
     # sticker_file_url = 'https://python-telegram-bot.org/static/testfiles/telegram.webp'
     # Serving sticker from gh since our server sends wrong content_type
@@ -245,12 +259,35 @@ class TestSticker(object):
 
 @pytest.fixture(scope='function')
 def sticker_set(bot):
-    ss = bot.get_sticker_set('test_by_{0}'.format(bot.username))
+    ss = bot.get_sticker_set('test_by_{}'.format(bot.username))
     if len(ss.stickers) > 100:
-        raise Exception('stickerset is growing too large.')
+        try:
+            for i in range(1, 50):
+                bot.delete_sticker_from_set(ss.stickers[-i].file_id)
+        except BadRequest:
+            raise Exception('stickerset is growing too large.')
     return ss
 
 
+@pytest.fixture(scope='function')
+def animated_sticker_set(bot):
+    ss = bot.get_sticker_set('animated_test_by_{}'.format(bot.username))
+    if len(ss.stickers) > 100:
+        try:
+            for i in range(1, 50):
+                bot.delete_sticker_from_set(ss.stickers[-i].file_id)
+        except BadRequest:
+            raise Exception('stickerset is growing too large.')
+    return ss
+
+
+@pytest.fixture(scope='function')
+def sticker_set_thumb_file():
+    f = open('tests/data/sticker_set_thumb.png', 'rb')
+    yield f
+    f.close()
+
+
 class TestStickerSet(object):
     title = 'Test stickers'
     is_animated = True
@@ -258,14 +295,15 @@ class TestStickerSet(object):
     stickers = [Sticker('file_id', 'file_un_id', 512, 512, True)]
     name = 'NOTAREALNAME'
 
-    def test_de_json(self, bot):
-        name = 'test_by_{0}'.format(bot.username)
+    def test_de_json(self, bot, sticker):
+        name = 'test_by_{}'.format(bot.username)
         json_dict = {
             'name': name,
             'title': self.title,
             'is_animated': self.is_animated,
             'contains_masks': self.contains_masks,
-            'stickers': [x.to_dict() for x in self.stickers]
+            'stickers': [x.to_dict() for x in self.stickers],
+            'thumb': sticker.thumb.to_dict()
         }
         sticker_set = StickerSet.de_json(json_dict, bot)
 
@@ -274,15 +312,28 @@ class TestStickerSet(object):
         assert sticker_set.is_animated == self.is_animated
         assert sticker_set.contains_masks == self.contains_masks
         assert sticker_set.stickers == self.stickers
+        assert sticker_set.thumb == sticker.thumb
 
     @flaky(3, 1)
     @pytest.mark.timeout(10)
-    def test_bot_methods_1(self, bot, chat_id):
+    def test_bot_methods_1_png(self, bot, chat_id, sticker_file):
         with open('tests/data/telegram_sticker.png', 'rb') as f:
             file = bot.upload_sticker_file(95205500, f)
         assert file
-        assert bot.add_sticker_to_set(chat_id, 'test_by_{0}'.format(bot.username),
-                                      file.file_id, '😄')
+        assert bot.add_sticker_to_set(chat_id, 'test_by_{}'.format(bot.username),
+                                      png_sticker=file.file_id, emojis='😄')
+        # Also test with file input and mask
+        assert bot.add_sticker_to_set(chat_id, 'test_by_{}'.format(bot.username),
+                                      png_sticker=sticker_file, emojis='😄',
+                                      mask_position=MaskPosition(MaskPosition.EYES, -1, 1, 2))
+
+    @flaky(3, 1)
+    @pytest.mark.timeout(10)
+    def test_bot_methods_1_tgs(self, bot, chat_id):
+        assert bot.add_sticker_to_set(
+            chat_id, 'animated_test_by_{}'.format(bot.username),
+            tgs_sticker=open('tests/data/telegram_animated_sticker.tgs', 'rb'),
+            emojis='😄')
 
     def test_sticker_set_to_dict(self, sticker_set):
         sticker_set_dict = sticker_set.to_dict()
@@ -296,17 +347,48 @@ class TestStickerSet(object):
 
     @flaky(3, 1)
     @pytest.mark.timeout(10)
-    def test_bot_methods_2(self, bot, sticker_set):
+    def test_bot_methods_2_png(self, bot, sticker_set):
         file_id = sticker_set.stickers[0].file_id
         assert bot.set_sticker_position_in_set(file_id, 1)
 
+    @flaky(3, 1)
+    @pytest.mark.timeout(10)
+    def test_bot_methods_2_tgs(self, bot, animated_sticker_set):
+        file_id = animated_sticker_set.stickers[0].file_id
+        assert bot.set_sticker_position_in_set(file_id, 1)
+
     @flaky(10, 1)
     @pytest.mark.timeout(10)
-    def test_bot_methods_3(self, bot, sticker_set):
+    def test_bot_methods_3_png(self, bot, chat_id, sticker_set_thumb_file):
+        sleep(1)
+        assert bot.set_sticker_set_thumb('test_by_{}'.format(bot.username), chat_id,
+                                         sticker_set_thumb_file)
+
+    @flaky(10, 1)
+    @pytest.mark.timeout(10)
+    def test_bot_methods_3_tgs(self, bot, chat_id, animated_sticker_file, animated_sticker_set):
+        sleep(1)
+        assert bot.set_sticker_set_thumb('animated_test_by_{}'.format(bot.username), chat_id,
+                                         animated_sticker_file)
+        file_id = animated_sticker_set.stickers[-1].file_id
+        # also test with file input and mask
+        assert bot.set_sticker_set_thumb('animated_test_by_{}'.format(bot.username), chat_id,
+                                         file_id)
+
+    @flaky(10, 1)
+    @pytest.mark.timeout(10)
+    def test_bot_methods_4_png(self, bot, sticker_set):
         sleep(1)
         file_id = sticker_set.stickers[-1].file_id
         assert bot.delete_sticker_from_set(file_id)
 
+    @flaky(10, 1)
+    @pytest.mark.timeout(10)
+    def test_bot_methods_4_tgs(self, bot, animated_sticker_set):
+        sleep(1)
+        file_id = animated_sticker_set.stickers[-1].file_id
+        assert bot.delete_sticker_from_set(file_id)
+
     def test_get_file_instance_method(self, monkeypatch, sticker):
         def test(*args, **kwargs):
             return args[1] == sticker.file_id

tests/test_updater.py

@@ -41,7 +41,7 @@ from future.builtins import bytes
 
 from telegram import TelegramError, Message, User, Chat, Update, Bot
 from telegram.error import Unauthorized, InvalidToken, TimedOut, RetryAfter
-from telegram.ext import Updater, Dispatcher, BasePersistence
+from telegram.ext import Updater, Dispatcher, DictPersistence
 
 signalskip = pytest.mark.skipif(sys.platform == 'win32',
                                 reason='Can\'t send signals without stopping '
@@ -467,7 +467,7 @@ class TestUpdater(object):
 
     def test_mutual_exclude_persistence_dispatcher(self):
         dispatcher = Dispatcher(None, None)
-        persistence = BasePersistence()
+        persistence = DictPersistence()
         with pytest.raises(ValueError):
             Updater(dispatcher=dispatcher, persistence=persistence)