Bump version to v<VERSION>

V12 changelog (#1480 )
* python3.4 is no longer supported * Prepare CHANGES.RST & README.rst for v12.0.0 release * CHANGES.rst: small fix * Add Bibo-Joshi to Credits * update the changelog - in anticipation for release * remove line about api 4.4 * fix spelling * move too long descriptions to wiki
2026-06-28 04:05:01 +00:00 · 2019-08-29 21:33:51 +03:00 · 2019-08-29 19:30:29 +02:00 · 2019-08-29 19:09:38 +02:00 · 2019-08-28 22:58:58 +03:00 · 2019-08-28 22:06:41 +03:00
198 changed files with 7965 additions and 2500 deletions
@@ -23,6 +23,11 @@ var/
 .installed.cfg
 *.egg
 .env
+.pybuild
+debian/tmp
+debian/python3-telegram
+debian/python3-telegram-doc
+debian/.debhelper

 # PyInstaller
 #  Usually these files are written by a python script from a template
@@ -1,17 +1,20 @@
+repos:
 -   repo: git://github.com/python-telegram-bot/mirrors-yapf
-    sha: master
+    sha: 5769e088ef6e0a0d1eb63bd6d0c1fe9f3606d6c8
    hooks:
    -   id: yapf
        files: ^(telegram|tests)/.*\.py$
        args:
        - --diff
 -   repo: git://github.com/pre-commit/pre-commit-hooks
-    sha: v1.2.0
+    sha: 0b70e285e369bcb24b57b74929490ea7be9c4b19
    hooks:
    -   id: flake8
        exclude: ^(setup.py|docs/source/conf.py)$
+        args:
+        - --ignore=W605,W503
 -   repo: git://github.com/pre-commit/mirrors-pylint
-    sha: v1.7.1
+    sha: 9d8dcbc2b86c796275680f239c1e90dcd50bd398
    hooks:
    -   id: pylint
        files: ^telegram/.*\.py$
@@ -1,11 +1,23 @@
 language: python
-python:
-  - "2.7"
-  - "3.4"
-  - "3.5"
-  - "3.6"
-  - "3.7-dev"
-  - "pypy-5.7.1"
+matrix:
+  include:
+    - python: 2.7
+    - python: 3.5
+    - python: 3.6
+    - python: 3.7
+      dist: xenial
+      sudo: true
+    - python: 3.7
+      dist: xenial
+      env: TEST_OFFICIAL=true
+    - python: pypy2.7-5.10.0
+      dist: xenial
+    - python: pypy3.5-5.10.1
+      dist: xenial
+  allow_failures:
+    - python: pypy2.7-5.10.0
+    - python: pypy3.5-5.10.1
+    - env: TEST_OFFICIAL=true

 dist: trusty
 sudo: false
@@ -13,6 +25,7 @@ sudo: false
 branches:
  only:
    - master
+    - /^[vV]\d+$/

 cache:
  directories:
@@ -31,8 +44,9 @@ install:
  - if [[ $TRAVIS_PYTHON_VERSION != 'pypy'* ]]; then pip install ujson; fi

 script:
-  - pytest -v -m nocoverage
-  - pytest -v -m "not nocoverage" --cov
+  - if [[ $TEST_OFFICIAL != 'true' ]]; then pytest -v -m nocoverage; fi
+  - if [[ $TEST_OFFICIAL != 'true' ]]; then pytest -v -m "not nocoverage" --cov; fi
+  - if [[ $TEST_OFFICIAL == 'true' ]]; then pytest -v tests/test_official.py; fi

 after_success:
  - coverage combine
@@ -4,7 +4,7 @@ Credits
 ``python-telegram-bot`` was originally created by
 `Leandro Toledo <https://github.com/leandrotoledo>`_ and is now maintained by
 `Jannes Höke <https://github.com/jh0ker>`_ (`@jh0ker <https://t.me/jh0ker>`_ on Telegram),
-`Noam Meltzer <https://github.com/tsnoam>`_, `Pieter Schutz <https://github.com/eldinnie>`_ and `Jasmin Bom <https://github.com/jsmnbom>`_.
+`Noam Meltzer <https://github.com/tsnoam>`_, `Pieter Schutz <https://github.com/eldinnie>`_, `Jasmin Bom <https://github.com/jsmnbom>`_ and `Hinrich Mahler <https://github.com/Bibo-Joshi>`_.

 We're vendoring urllib3 as part of ``python-telegram-bot`` which is distributed under the MIT
 license. For more info, full credits & license terms, the sources can be found here:
@@ -16,18 +16,23 @@ Contributors
 The following wonderful people contributed directly or indirectly to this project:

 - `Alateas <https://github.com/alateas>`_
+- `Ales Dokshanin <https://github.com/alesdokshanin>`_
+- `Ambro17 <https://github.com/Ambro17>`_
 - `Anton Tagunov <https://github.com/anton-tagunov>`_
 - `Avanatiker <https://github.com/Avanatiker>`_
 - `Balduro <https://github.com/Balduro>`_
+- `Bibo-Joshi <https://github.com/Bibo-Joshi>`_
 - `bimmlerd <https://github.com/bimmlerd>`_
 - `d-qoi <https://github.com/d-qoi>`_
 - `daimajia <https://github.com/daimajia>`_
 - `Daniel Reed <https://github.com/nmlorg>`_
+- `Ehsan Online <https://github.com/ehsanonline>`_
 - `Eli Gao <https://github.com/eligao>`_
 - `Emilio Molinari <https://github.com/xates>`_
 - `ErgoZ Riftbit Vaper <https://github.com/ergoz>`_
 - `Eugene Lisitsky <https://github.com/lisitsky>`_
 - `Eugenio Panadero <https://github.com/azogue>`_
+- `Evan Haberecht <https://github.com/habereet>`_
 - `evgfilim1 <https://github.com/evgfilim1>`_
 - `franciscod <https://github.com/franciscod>`_
 - `Hugo Damer <https://github.com/HakimusGIT>`_
@@ -42,8 +47,10 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Joscha Götzer <https://github.com/Rostgnom>`_
 - `jossalgon <https://github.com/jossalgon>`_
 - `JRoot3D <https://github.com/JRoot3D>`_
+- `Kirill Vasin <https://github.com/vasinkd>`_
 - `Kjwon15 <https://github.com/kjwon15>`_
 - `Li-aung Yip <https://github.com/LiaungYip>`_
+- `Loo Zheng Yuan <https://github.com/loozhengyuan>`_
 - `macrojames <https://github.com/macrojames>`_
 - `Michael Elovskikh <https://github.com/wronglink>`_
 - `Mischa Krüger <https://github.com/Makman2>`_
@@ -58,6 +65,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Patrick Hofmann <https://github.com/PH89>`_
 - `Paul Larsen <https://github.com/PaulSonOfLars>`_
 - `Pieter Schutz <https://github.com/eldinnie>`_
+- `Poolitzer <https://github.com/Poolitzer>`_
 - `Rahiel Kasim <https://github.com/rahiel>`_
 - `Sascha <https://github.com/saschalalala>`_
 - `Shelomentsev D <https://github.com/shelomentsevd>`_
@@ -67,6 +75,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Trainer Jono <https://github.com/Tr-Jono>`_
 - `Valentijn <https://github.com/Faalentijn>`_
 - `voider1 <https://github.com/voider1>`_
+- `Vorobjev Simon <https://github.com/simonvorobjev>`_
 - `Wagner Macedo <https://github.com/wagnerluis1982>`_
 - `wjt <https://github.com/wjt>`_

@@ -1,9 +1,164 @@
-=======
-Changes
-=======
+=========
+Changelog
+=========

-**2018-09-01**
-*Released 11.1.0*
+Version 12.0.0
+================
+*Released 2019-08-29*
+
+Well... This felt like decades. But here we are with a new release.
+
+Expect minor releases soon (mainly complete Bot API 4.4 support)
+
+**Major and/or breaking changes:**
+
+- Context based callbacks
+- Persistence
+- PrefixHandler added (Handler overhaul)
+- Deprecation of RegexHandler and edited_messages, channel_post, etc. arguments (Filter overhaul)
+- Various ConversationHandler changes and fixes
+- Bot API 4.1, 4.2, 4.3 support
+- Python 3.4 is no longer supported
+- Error Handler now handles all types of exceptions (`#1485`_)
+- Return UTC from from_timestamp() (`#1485`_)
+
+**See the wiki page at https://git.io/fxJuV for a detailed guide on how to migrate from version 11 to version 12.**
+
+Context based callbacks (`#1100`_)
+----------------------------------
+
+- Use of ``pass_`` in handlers is deprecated.
+- Instead use ``use_context=True`` on ``Updater`` or ``Dispatcher`` and change callback from (bot, update, others...) to (update, context).
+- This also applies to error handlers ``Dispatcher.add_error_handler`` and JobQueue jobs (change (bot, job) to (context) here).
+- For users with custom handlers subclassing Handler, this is mostly backwards compatible, but to use the new context based callbacks you need to implement the new collect_additional_context method.
+- Passing bot to ``JobQueue.__init__`` is deprecated. Use JobQueue.set_dispatcher with a dispatcher instead.
+- Dispatcher makes sure to use a single `CallbackContext` for a entire update. This means that if an update is handled by multiple handlers (by using the group argument), you can add custom arguments to the `CallbackContext` in a lower group handler and use it in higher group handler. NOTE: Never use with @run_async, see docs for more info. (`#1283`_)
+- If you have custom handlers they will need to be updated to support the changes in this release.
+- Update all examples to use context based callbacks.
+
+Persistence (`#1017`_)
+----------------------
+
+- Added PicklePersistence and DictPersistence for adding persistence to your bots.
+- BasePersistence can be subclassed for all your persistence needs.
+- Add a new example that shows a persistent ConversationHandler bot
+
+Handler overhaul (`#1114`_)
+---------------------------
+
+- CommandHandler now only triggers on actual commands as defined by telegram servers (everything that the clients mark as a tabable link).
+- PrefixHandler can be used if you need to trigger on prefixes (like all messages starting with a "/" (old CommandHandler behaviour) or even custom prefixes like "#" or "!").
+
+Filter overhaul (`#1221`_)
+--------------------------
+
+- RegexHandler is deprecated and should be replaced with a MessageHandler with a regex filter.
+- Use update filters to filter update types instead of arguments (message_updates, channel_post_updates and edited_updates) on the handlers.
+- Completely remove allow_edited argument - it has been deprecated for a while.
+- data_filters now exist which allows filters that return data into the callback function. This is how the regex filter is implemented.
+- All this means that it no longer possible to use a list of filters in a handler. Use bitwise operators instead!
+
+ConversationHandler
+-------------------
+
+- Remove ``run_async_timeout`` and ``timed_out_behavior`` arguments (`#1344`_)
+- Replace with ``WAITING`` constant and behavior from states (`#1344`_)
+- Only emit one warning for multiple CallbackQueryHandlers in a ConversationHandler (`#1319`_)
+- Use warnings.warn for ConversationHandler warnings (`#1343`_)
+- Fix unresolvable promises (`#1270`_)
+
+
+Bug fixes & improvements
+------------------------
+
+- Handlers should be faster due to deduped logic.
+- Avoid compiling compiled regex in regex filter. (`#1314`_)
+- Add missing ``left_chat_member`` to Message.MESSAGE_TYPES (`#1336`_)
+- Make custom timeouts actually work properly (`#1330`_)
+- Add convenience classmethods (from_button, from_row and from_column) to InlineKeyboardMarkup
+- Small typo fix in setup.py (`#1306`_)
+- Add Conflict error (HTTP error code 409) (`#1154`_)
+- Change MAX_CAPTION_LENGTH to 1024 (`#1262`_)
+- Remove some unnecessary clauses (`#1247`_, `#1239`_)
+- Allow filenames without dots in them when sending files (`#1228`_)
+- Fix uploading files with unicode filenames (`#1214`_)
+- Replace http.server with Tornado (`#1191`_)
+- Allow SOCKSConnection to parse username and password from URL (`#1211`_)
+- Fix for arguments in passport/data.py (`#1213`_)
+- Improve message entity parsing by adding text_mention (`#1206`_)
+- Documentation fixes (`#1348`_, `#1397_`, `#1436`_)
+- Merged filters short-circuit (`#1350`_)
+- Fix webhook listen with tornado (`#1383`_)
+- Call task_done() on update queue after update processing finished (`#1428`_)
+- Fix send_location() - latitude may be 0 (`#1437`_)
+- Make MessageEntity objects comparable (`#1465`_)
+- Add prefix to thread names (`#1358`_)
+
+Buf fixes since v12.0.0b1
+-------------------------
+
+- Fix setting bot on ShippingQuery (`#1355`_)
+- Fix _trigger_timeout() missing 1 required positional argument: 'job' (`#1367`_)
+- Add missing message.text check in PrefixHandler check_update (`#1375`_)
+- Make updates persist even on DispatcherHandlerStop (`#1463`_)
+- Dispatcher force updating persistence object's chat data attribute(`#1462`)
+
+.. _`#1100`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1100
+.. _`#1283`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1283
+.. _`#1017`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1017
+.. _`#1325`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1325
+.. _`#1301`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1301
+.. _`#1312`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1312
+.. _`#1324`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1324
+.. _`#1114`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1114
+.. _`#1221`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1221
+.. _`#1314`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1314
+.. _`#1336`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1336
+.. _`#1330`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1330
+.. _`#1306`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1306
+.. _`#1154`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1154
+.. _`#1262`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1262
+.. _`#1247`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1247
+.. _`#1239`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1239
+.. _`#1228`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1228
+.. _`#1214`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1214
+.. _`#1191`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1191
+.. _`#1211`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1211
+.. _`#1213`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1213
+.. _`#1206`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1206
+.. _`#1344`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1344
+.. _`#1319`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1319
+.. _`#1343`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1343
+.. _`#1270`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1270
+.. _`#1348`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1348
+.. _`#1350`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1350
+.. _`#1383`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1383
+.. _`#1397`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1397
+.. _`#1428`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1428
+.. _`#1436`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1436
+.. _`#1437`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1437
+.. _`#1465`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1465
+.. _`#1358`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1358
+.. _`#1355`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1355
+.. _`#1367`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1367
+.. _`#1375`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1375
+.. _`#1463`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1463
+.. _`#1462`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1462
+.. _`#1483`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1483
+.. _`#1485`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1485
+
+Internal improvements
+---------------------
+
+- Finally fix our CI builds mostly (too many commits and PRs to list)
+- Use multiple bots for CI to improve testing times significantly.
+- Allow pypy to fail in CI.
+- Remove the last CamelCase CheckUpdate methods from the handlers we missed earlier.
+- test_official is now executed in a different job
+
+Version 11.1.0
+==============
+*Released 2018-09-01*

 Fixes and updates for Telegram Passport: (`#1198`_)

@@ -17,8 +172,9 @@ Fixes and updates for Telegram Passport: (`#1198`_)

 .. _`#1198`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1198

-**2018-08-29**
-*Released 11.0.0*
+Version 11.0.0
+==============
+*Released 2018-08-29*

 Fully support Bot API version 4.0!
 (also some bugfixes :))
@@ -73,8 +229,9 @@ Non Bot API 4.0 changes:
 .. _`#1184`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1184
 .. _`our telegram passport wiki page`: https://git.io/fAvYd

-**2018-05-02**
-*Released 10.1.0*
+Version 10.1.0
+==============
+*Released 2018-05-02*

 Fixes changing previous behaviour:

@@ -100,8 +257,9 @@ Fixes:
 .. _`#1096`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1096
 .. _`#1099`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1099

-**2018-04-17**
-*Released 10.0.2*
+Version 10.0.2
+==============
+*Released 2018-04-17*

 Important fix:

@@ -132,8 +290,9 @@ Fixes:
 .. _`#1076`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1076
 .. _`#1071`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1071

-**2018-03-05**
-*Released 10.0.1*
+Version 10.0.1
+==============
+*Released 2018-03-05*

 Fixes:

@@ -143,8 +302,9 @@ Fixes:
 .. _`#1032`: https://github.com/python-telegram-bot/python-telegram-bot/pull/826
 .. _`#912`: https://github.com/python-telegram-bot/python-telegram-bot/pull/826

-**2018-03-02**
-*Released 10.0.0*
+Version 10.0.0
+==============
+*Released 2018-03-02*

 Non backward compatabile changes and changed defaults

@@ -209,8 +369,9 @@ Changes
 .. _`#1019`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1019
 .. _`#1020`: https://github.com/python-telegram-bot/python-telegram-bot/pull/1020

-**2017-12-08**
-*Released 9.0.0*
+Version 9.0.0
+=============
+*Released 2017-12-08*

 Breaking changes (possibly)

@@ -235,15 +396,17 @@ Changes
 .. _`#694`: https://github.com/python-telegram-bot/python-telegram-bot/pull/694
 .. _`#870`: https://github.com/python-telegram-bot/python-telegram-bot/pull/870

-**2017-10-15**
-*Released 8.1.1*
+Version 8.1.1
+=============
+*Released 2017-10-15*

 - Fix Commandhandler crashing on single character messages (PR `#873`_).

 .. _`#873`: https://github.com/python-telegram-bot/python-telegram-bot/pull/871

-**2017-10-14**
-*Released 8.1.0*
+Version 8.1.0
+=============
+*Released 2017-10-14*

 New features
 - Support Bot API 3.4 (PR `#865`_).
@@ -260,8 +423,9 @@ Changes
 .. _`#865`: https://github.com/python-telegram-bot/python-telegram-bot/pull/865
 .. _`#869`: https://github.com/python-telegram-bot/python-telegram-bot/pull/869

-**2017-09-01**
-*Released 8.0.0*
+Version 8.0.0
+=============
+*Released 2017-09-01*

 New features

@@ -302,14 +466,16 @@ Changes
 .. _`#793`: https://github.com/python-telegram-bot/python-telegram-bot/pull/793
 .. _`#810`: https://github.com/python-telegram-bot/python-telegram-bot/pull/810

-**2017-07-28**
-*Released 7.0.1*
+Version 7.0.1
+===============
+*Released 2017-07-28*

 - Fix TypeError exception in RegexHandler (PR #751).
 - Small documentation fix (PR #749).

-**2017-07-25**
-*Released 7.0.0*
+Version 7.0.0
+=============
+*Released 2017-07-25*

 - Fully support Bot API 3.2.
 - New filters for handling messages from specific chat/user id (PR #677).
@@ -327,6 +493,9 @@ Changes
 - Improved documentation.
 - Improved unitests.

+Pre-version 7.0
+===============
+
 **2017-06-18**

 *Released 6.1.0*
@@ -46,6 +46,10 @@ We have a vibrant community of developers helping each other in our `Telegram gr
   :target: http://isitmaintained.com/project/python-telegram-bot/python-telegram-bot
   :alt: Median time to resolve an issue

+.. image:: https://api.codacy.com/project/badge/Grade/99d901eaa09b44b4819aec05c330c968
+   :target: https://www.codacy.com/app/python-telegram-bot/python-telegram-bot?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=python-telegram-bot/python-telegram-bot&amp;utm_campaign=Badge_Grade
+   :alt: Code quality
+
 .. image:: https://img.shields.io/badge/Telegram-Group-blue.svg
   :target: https://telegram.me/pythontelegrambotgroup
   :alt: Telegram Group
@@ -85,7 +89,6 @@ Introduction
 This library provides a pure Python interface for the
 `Telegram Bot API <https://core.telegram.org/bots/api>`_.
 It's compatible with Python versions 2.7, 3.3+ and `PyPy <http://pypy.org/>`_.
-It also works with `Google App Engine <https://cloud.google.com/appengine>`_.

 In addition to the pure API implementation, this library features a number of high-level classes to
 make the development of bots easy and straightforward. These classes are contained in the
@@ -7,13 +7,14 @@ environment:
    # isn't covered by this document) at the time of writing.

    - PYTHON: "C:\\Python27"
-    - PYTHON: "C:\\Python34"
    - PYTHON: "C:\\Python35"
    - PYTHON: "C:\\Python36"
+    - PYTHON: "C:\\Python37"

 branches:
  only:
  - master
+  - /^[vV]\d+$/

 skip_branch_with_pr: true

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+cp -R contrib/debian .
+debuild -us -uc
+debian/rules clean
+rm -rf debian
+
@@ -0,0 +1,6 @@
+telegram (12.0.0b1) unstable; urgency=medium
+
+  * Debian packaging;
+  * Initial Release.
+
+ -- Marco Marinello <me@marcomarinello.it>  Thu, 22 Aug 2019 20:36:47 +0200
@@ -0,0 +1 @@
+11
@@ -0,0 +1,25 @@
+Source: telegram
+Section: utils
+Priority: optional
+Maintainer: Marco Marinello <me@marcomarinello.it>
+Build-Depends: debhelper (>= 11), dh-python, python3-all, python3-setuptools
+Standards-Version: 4.1.3
+Homepage: https://python-telegram-bot.org
+X-Python-Version: >= 3.2
+Vcs-Browser: https://github.com/python-telegram-bot/python-telegram-bot
+Vcs-Git: https://github.com/python-telegram-bot/python-telegram-bot.git
+
+Package: python3-telegram-bot
+Architecture: any
+Depends: ${python3:Depends}, ${misc:Depends}
+Description: We have made you a wrapper you can't refuse!
+ The Python Telegram bot (Python 3)
+ This library provides a pure Python interface for the Telegram Bot API.
+ It's compatible with Python versions 2.7, 3.3+ and PyPy.
+ .
+ In addition to the pure API implementation, this library features
+ a number of high-level
+ classes to make the development of bots easy and straightforward.
+ These classes are contained in the telegram.ext submodule.
+ .
+ This package installs the library for Python 3.
@@ -0,0 +1,30 @@
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: telegram
+Source: https://github.com/python-telegram-bot/python-telegram-bot
+
+Files: *
+Copyright: 2019 Leandro Toledo
+           2019 see AUTHORS file
+License: LGPLv3
+
+Files: debian/*
+Copyright: 2019 Marco Marinello <me@marcomarinello.it>
+License: GPL-3.0+
+
+License: GPL-3.0+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+ .
+ This package 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 General Public License for more details.
+ .
+ You should have received a copy of the GNU General Public License
+ along with this program. If not, see <https://www.gnu.org/licenses/>.
+ .
+ On Debian systems, the complete text of the GNU General
+ Public License version 3 can be found in "/usr/share/common-licenses/GPL-3".
+
@@ -0,0 +1 @@
+AUTHORS.rst	/usr/share/doc/python3-telegram-bot
@@ -0,0 +1,18 @@
+#!/usr/bin/make -f
+# See debhelper(7) (uncomment to enable)
+# output every command that modifies files on the build system.
+#export DH_VERBOSE = 1
+
+export PYBUILD_NAME=telegram
+
+%:
+	DEB_BUILD_OPTIONS=nocheck dh $@ --with python2,python3 --buildsystem=pybuild
+
+
+# If you need to rebuild the Sphinx documentation
+# Add spinxdoc to the dh --with line
+#override_dh_auto_build:
+#	dh_auto_build
+#	PYTHONPATH=. http_proxy='127.0.0.1:9' sphinx-build -N -bhtml        docs/ build/html # HTML generator
+#	PYTHONPATH=. http_proxy='127.0.0.1:9' sphinx-build -N -bman        docs/ build/man # Manpage generator
+
@@ -0,0 +1 @@
+3.0 (native)
@@ -0,0 +1 @@
+extend-diff-ignore = "^[^/]*[.]egg-info/"
@@ -1,3 +1,3 @@
-sphinx>=1.5.4
+sphinx>=1.7.9
 sphinx_rtd_theme
 sphinx-pypi-upload
@@ -0,0 +1 @@
+.. include:: ../../CHANGES.rst
@@ -24,7 +24,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 # -- General configuration ------------------------------------------------

 # If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = '1.5.4'  # fixes issues with autodoc-skip-member and napoleon
+needs_sphinx = '1.7.9'

 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -58,9 +58,9 @@ author = u'Leandro Toledo'
 # built documents.
 #
 # The short X.Y version.
-version = '11.1'  # telegram.__version__[:3]
+version = '12.0'  # telegram.__version__[:3]
 # The full version, including alpha/beta/rc tags.
-release = '11.1.0'  # telegram.__version__
+release = '12.0.0'  # telegram.__version__

 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -289,6 +289,10 @@ texinfo_documents = [
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False

+# Napoleon stuff
+
+napoleon_use_admonition_for_examples = True
+
 # -- script stuff --------------------------------------------------------


@@ -6,8 +6,23 @@
 Welcome to Python Telegram Bot's documentation!
 ===============================================

-Below you can find the documentation for the python-telegram-bot library. except for the .ext package most of the
-objects in the package reflect the types as defined by the `telegram bot api <https://core.telegram.org/bots/api>`_.
+Guides and tutorials
+====================
+
+If you're just starting out with the library, we recommend following our `"Your first Bot" <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions-%E2%80%93-Your-first-Bot>`_ tutorial that you can find on our `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki>`_.
+On our wiki you will also find guides like how to use handlers, webhooks, emoji, proxies and much more.
+
+Examples
+========
+
+A great way to learn is by looking at examples. Ours can be found at our `github in the examples folder <https://github.com/python-telegram-bot/python-telegram-bot/tree/master/examples>`_.
+
+
+Reference
+=========
+
+Below you can find a reference of all the classes and methods in python-telegram-bot.
+Apart from the telegram.ext package the objects should reflect the types defined in the `official telegram bot api documentation <https://core.telegram.org/bots/api>`_

 .. toctree::
   telegram
@@ -15,13 +30,9 @@ objects in the package reflect the types as defined by the `telegram bot api <ht
 Changelog
 ---------

-.. include:: ../../CHANGES.rst
+.. toctree::
+   :maxdepth: 2

-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   changelog


@@ -0,0 +1,6 @@
+telegram.ext.BasePersistence
+============================
+
+.. autoclass:: telegram.ext.BasePersistence
+    :members:
+    :show-inheritance:
@@ -0,0 +1,5 @@
+telegram.ext.CallbackContext
+============================
+
+.. autoclass:: telegram.ext.CallbackContext
+    :members:
@@ -0,0 +1,6 @@
+telegram.ext.DictPersistence
+============================
+
+.. autoclass:: telegram.ext.DictPersistence
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+telegram.ext.PicklePersistence
+==============================
+
+.. autoclass:: telegram.ext.PicklePersistence
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+telegram.ext.PrefixHandler
+===========================
+
+.. autoclass:: telegram.ext.PrefixHandler
+    :members:
+    :show-inheritance:
@@ -10,6 +10,7 @@ telegram.ext package
    telegram.ext.jobqueue
    telegram.ext.messagequeue
    telegram.ext.delayqueue
+    telegram.ext.callbackcontext

 Handlers
 --------
@@ -24,8 +25,18 @@ Handlers
    telegram.ext.inlinequeryhandler
    telegram.ext.messagehandler
    telegram.ext.precheckoutqueryhandler
+    telegram.ext.prefixhandler
    telegram.ext.regexhandler
    telegram.ext.shippingqueryhandler
    telegram.ext.stringcommandhandler
    telegram.ext.stringregexhandler
    telegram.ext.typehandler
+
+Persistence
+-----------
+
+.. toctree::
+
+    telegram.ext.basepersistence
+    telegram.ext.picklepersistence
+    telegram.ext.dictpersistence
@@ -0,0 +1,6 @@
+telegram.Poll
+=============
+
+.. autoclass:: telegram.Poll
+    :members:
+    :show-inheritance:
@@ -0,0 +1,6 @@
+telegram.PollOption
+===================
+
+.. autoclass:: telegram.PollOption
+    :members:
+    :show-inheritance:
@@ -1,117 +1,120 @@
+.. include:: telegram.ext.rst
+
+
 telegram package
 ================

 .. toctree::

-   telegram.ext
-   telegram.utils
-   telegram.animation
-   telegram.audio
-   telegram.bot
-   telegram.callbackquery
-   telegram.chat
-   telegram.chataction
-   telegram.chatmember
-   telegram.chatphoto
-   telegram.constants
-   telegram.contact
-   telegram.document
-   telegram.error
-   telegram.file
-   telegram.forcereply
-   telegram.inlinekeyboardbutton
-   telegram.inlinekeyboardmarkup
-   telegram.inputfile
-   telegram.inputmedia
-   telegram.inputmediaanimation
-   telegram.inputmediaaudio
-   telegram.inputmediadocument
-   telegram.inputmediaphoto
-   telegram.inputmediavideo
-   telegram.keyboardbutton
-   telegram.location
-   telegram.message
-   telegram.messageentity
-   telegram.parsemode
-   telegram.photosize
-   telegram.replykeyboardremove
-   telegram.replykeyboardmarkup
-   telegram.replymarkup
-   telegram.telegramobject
-   telegram.update
-   telegram.user
-   telegram.userprofilephotos
-   telegram.venue
-   telegram.video
-   telegram.videonote
-   telegram.voice
-   telegram.webhookinfo
+    telegram.animation
+    telegram.audio
+    telegram.bot
+    telegram.callbackquery
+    telegram.chat
+    telegram.chataction
+    telegram.chatmember
+    telegram.chatphoto
+    telegram.constants
+    telegram.contact
+    telegram.document
+    telegram.error
+    telegram.file
+    telegram.forcereply
+    telegram.inlinekeyboardbutton
+    telegram.inlinekeyboardmarkup
+    telegram.inputfile
+    telegram.inputmedia
+    telegram.inputmediaanimation
+    telegram.inputmediaaudio
+    telegram.inputmediadocument
+    telegram.inputmediaphoto
+    telegram.inputmediavideo
+    telegram.keyboardbutton
+    telegram.location
+    telegram.message
+    telegram.messageentity
+    telegram.parsemode
+    telegram.photosize
+    telegram.poll
+    telegram.polloption
+    telegram.replykeyboardremove
+    telegram.replykeyboardmarkup
+    telegram.replymarkup
+    telegram.telegramobject
+    telegram.update
+    telegram.user
+    telegram.userprofilephotos
+    telegram.venue
+    telegram.video
+    telegram.videonote
+    telegram.voice
+    telegram.webhookinfo

 Stickers
 --------

 .. toctree::

-   telegram.sticker
-   telegram.stickerset
-   telegram.maskposition
+    telegram.sticker
+    telegram.stickerset
+    telegram.maskposition

 Inline Mode
 -----------

 .. toctree::

-   telegram.inlinequery
-   telegram.inlinequeryresult
-   telegram.inlinequeryresultarticle
-   telegram.inlinequeryresultaudio
-   telegram.inlinequeryresultcachedaudio
-   telegram.inlinequeryresultcacheddocument
-   telegram.inlinequeryresultcachedgif
-   telegram.inlinequeryresultcachedmpeg4gif
-   telegram.inlinequeryresultcachedphoto
-   telegram.inlinequeryresultcachedsticker
-   telegram.inlinequeryresultcachedvideo
-   telegram.inlinequeryresultcachedvoice
-   telegram.inlinequeryresultcontact
-   telegram.inlinequeryresultdocument
-   telegram.inlinequeryresultgame
-   telegram.inlinequeryresultgif
-   telegram.inlinequeryresultlocation
-   telegram.inlinequeryresultmpeg4gif
-   telegram.inlinequeryresultphoto
-   telegram.inlinequeryresultvenue
-   telegram.inlinequeryresultvideo
-   telegram.inlinequeryresultvoice
-   telegram.inputmessagecontent
-   telegram.inputtextmessagecontent
-   telegram.inputlocationmessagecontent
-   telegram.inputvenuemessagecontent
-   telegram.inputcontactmessagecontent
-   telegram.choseninlineresult
+    telegram.inlinequery
+    telegram.inlinequeryresult
+    telegram.inlinequeryresultarticle
+    telegram.inlinequeryresultaudio
+    telegram.inlinequeryresultcachedaudio
+    telegram.inlinequeryresultcacheddocument
+    telegram.inlinequeryresultcachedgif
+    telegram.inlinequeryresultcachedmpeg4gif
+    telegram.inlinequeryresultcachedphoto
+    telegram.inlinequeryresultcachedsticker
+    telegram.inlinequeryresultcachedvideo
+    telegram.inlinequeryresultcachedvoice
+    telegram.inlinequeryresultcontact
+    telegram.inlinequeryresultdocument
+    telegram.inlinequeryresultgame
+    telegram.inlinequeryresultgif
+    telegram.inlinequeryresultlocation
+    telegram.inlinequeryresultmpeg4gif
+    telegram.inlinequeryresultphoto
+    telegram.inlinequeryresultvenue
+    telegram.inlinequeryresultvideo
+    telegram.inlinequeryresultvoice
+    telegram.inputmessagecontent
+    telegram.inputtextmessagecontent
+    telegram.inputlocationmessagecontent
+    telegram.inputvenuemessagecontent
+    telegram.inputcontactmessagecontent
+    telegram.choseninlineresult

 Payments
 --------

 .. toctree::

-   telegram.labeledprice
-   telegram.invoice
-   telegram.shippingaddress
-   telegram.orderinfo
-   telegram.shippingoption
-   telegram.successfulpayment
-   telegram.shippingquery
-   telegram.precheckoutquery
+    telegram.labeledprice
+    telegram.invoice
+    telegram.shippingaddress
+    telegram.orderinfo
+    telegram.shippingoption
+    telegram.successfulpayment
+    telegram.shippingquery
+    telegram.precheckoutquery

 Games
 -----

 .. toctree::

-   telegram.game
-   telegram.callbackgame
-   telegram.gamehighscore
+    telegram.game
+    telegram.callbackgame
+    telegram.gamehighscore

 Passport
 --------
@@ -137,12 +140,8 @@ Passport
    telegram.encryptedpassportelement
    telegram.encryptedcredentials

+telegram.utils
+--------------

-Module contents
---------------
-
-.. automodule:: telegram
-    :members:
-    :undoc-members:
-    :show-inheritance:
-    :noindex:
+.. toctree::
+    telegram.utils
@@ -25,5 +25,8 @@ A basic example of an [inline bot](https://core.telegram.org/bots/inline). Don't
 ### [`paymentbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/paymentbot.py)
 A basic example of a bot that can accept payments. Don't forget to enable and configure payments with [@BotFather](https://telegram.me/BotFather).

+### [`persistentconversationbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/persistentconversationbot.py)
+A basic example of a bot store conversation state and user_data over multiple restarts.
+
 ## Pure API
 The [`echobot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/echobot.py) example uses only the pure, "bare-metal" API wrapper. 
@@ -1,11 +1,12 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-#
-# Simple Bot to reply to Telegram messages
 # This program is dedicated to the public domain under the CC0 license.
-"""
-This Bot uses the Updater class to handle the bot.
+#
+# THIS EXAMPLE HAS BEEN UPDATED TO WORK WITH THE BETA VERSION 12 OF PYTHON-TELEGRAM-BOT.
+# If you're still using version 11.1.0, please see the examples at
+# https://github.com/python-telegram-bot/python-telegram-bot/tree/v11.1.0/examples

+"""
 First, a few callback functions are defined. Then, those functions are passed to
 the Dispatcher and registered at their respective places.
 Then, the bot is started and runs until we press Ctrl-C on the command line.
@@ -17,12 +18,12 @@ Press Ctrl-C on the command line or send a signal to the process to stop the
 bot.
 """

-from telegram import (ReplyKeyboardMarkup, ReplyKeyboardRemove)
-from telegram.ext import (Updater, CommandHandler, MessageHandler, Filters, RegexHandler,
-                          ConversationHandler)
-
 import logging

+from telegram import (ReplyKeyboardMarkup, ReplyKeyboardRemove)
+from telegram.ext import (Updater, CommandHandler, MessageHandler, Filters,
+                          ConversationHandler)
+
 # Enable logging
 logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
                    level=logging.INFO)
@@ -32,7 +33,7 @@ logger = logging.getLogger(__name__)
 GENDER, PHOTO, LOCATION, BIO = range(4)


-def start(bot, update):
+def start(update, context):
    reply_keyboard = [['Boy', 'Girl', 'Other']]

    update.message.reply_text(
@@ -44,7 +45,7 @@ def start(bot, update):
    return GENDER


-def gender(bot, update):
+def gender(update, context):
    user = update.message.from_user
    logger.info("Gender of %s: %s", user.first_name, update.message.text)
    update.message.reply_text('I see! Please send me a photo of yourself, '
@@ -54,9 +55,9 @@ def gender(bot, update):
    return PHOTO


-def photo(bot, update):
+def photo(update, context):
    user = update.message.from_user
-    photo_file = bot.get_file(update.message.photo[-1].file_id)
+    photo_file = update.message.photo[-1].get_file()
    photo_file.download('user_photo.jpg')
    logger.info("Photo of %s: %s", user.first_name, 'user_photo.jpg')
    update.message.reply_text('Gorgeous! Now, send me your location please, '
@@ -65,7 +66,7 @@ def photo(bot, update):
    return LOCATION


-def skip_photo(bot, update):
+def skip_photo(update, context):
    user = update.message.from_user
    logger.info("User %s did not send a photo.", user.first_name)
    update.message.reply_text('I bet you look great! Now, send me your location please, '
@@ -74,7 +75,7 @@ def skip_photo(bot, update):
    return LOCATION


-def location(bot, update):
+def location(update, context):
    user = update.message.from_user
    user_location = update.message.location
    logger.info("Location of %s: %f / %f", user.first_name, user_location.latitude,
@@ -85,7 +86,7 @@ def location(bot, update):
    return BIO


-def skip_location(bot, update):
+def skip_location(update, context):
    user = update.message.from_user
    logger.info("User %s did not send a location.", user.first_name)
    update.message.reply_text('You seem a bit paranoid! '
@@ -94,7 +95,7 @@ def skip_location(bot, update):
    return BIO


-def bio(bot, update):
+def bio(update, context):
    user = update.message.from_user
    logger.info("Bio of %s: %s", user.first_name, update.message.text)
    update.message.reply_text('Thank you! I hope we can talk again some day.')
@@ -102,7 +103,7 @@ def bio(bot, update):
    return ConversationHandler.END


-def cancel(bot, update):
+def cancel(update, context):
    user = update.message.from_user
    logger.info("User %s canceled the conversation.", user.first_name)
    update.message.reply_text('Bye! I hope we can talk again some day.',
@@ -111,14 +112,16 @@ def cancel(bot, update):
    return ConversationHandler.END


-def error(bot, update, error):
+def error(update, context):
    """Log Errors caused by Updates."""
-    logger.warning('Update "%s" caused error "%s"', update, error)
+    logger.warning('Update "%s" caused error "%s"', update, context.error)


 def main():
-    # Create the EventHandler and pass it your bot's token.
-    updater = Updater("TOKEN")
+    # Create the Updater and pass it your bot's token.
+    # Make sure to set use_context=True to use the new context based callbacks
+    # Post version 12 this will no longer be necessary
+    updater = Updater("TOKEN", use_context=True)

    # Get the dispatcher to register handlers
    dp = updater.dispatcher
@@ -128,7 +131,7 @@ def main():
        entry_points=[CommandHandler('start', start)],

        states={
-            GENDER: [RegexHandler('^(Boy|Girl|Other)$', gender)],
+            GENDER: [MessageHandler(Filters.regex('^(Boy|Girl|Other)$'), gender)],

            PHOTO: [MessageHandler(Filters.photo, photo),
                    CommandHandler('skip', skip_photo)],
@@ -1,11 +1,12 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-#
-# Simple Bot to reply to Telegram messages
 # This program is dedicated to the public domain under the CC0 license.
-"""
-This Bot uses the Updater class to handle the bot.
+#
+# THIS EXAMPLE HAS BEEN UPDATED TO WORK WITH THE BETA VERSION 12 OF PYTHON-TELEGRAM-BOT.
+# If you're still using version 11.1.0, please see the examples at
+# https://github.com/python-telegram-bot/python-telegram-bot/tree/v11.1.0/examples

+"""
 First, a few callback functions are defined. Then, those functions are passed to
 the Dispatcher and registered at their respective places.
 Then, the bot is started and runs until we press Ctrl-C on the command line.
@@ -17,12 +18,12 @@ Press Ctrl-C on the command line or send a signal to the process to stop the
 bot.
 """

-from telegram import ReplyKeyboardMarkup
-from telegram.ext import (Updater, CommandHandler, MessageHandler, Filters, RegexHandler,
-                          ConversationHandler)
-
 import logging

+from telegram import ReplyKeyboardMarkup
+from telegram.ext import (Updater, CommandHandler, MessageHandler, Filters,
+                          ConversationHandler)
+
 # Enable logging
 logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
                    level=logging.INFO)
@@ -46,7 +47,7 @@ def facts_to_str(user_data):
    return "\n".join(facts).join(['\n', '\n'])


-def start(bot, update):
+def start(update, context):
    update.message.reply_text(
        "Hi! My name is Doctor Botter. I will hold a more complex conversation with you. "
        "Why don't you tell me something about yourself?",
@@ -55,37 +56,39 @@ def start(bot, update):
    return CHOOSING


-def regular_choice(bot, update, user_data):
+def regular_choice(update, context):
    text = update.message.text
-    user_data['choice'] = text
+    context.user_data['choice'] = text
    update.message.reply_text(
        'Your {}? Yes, I would love to hear about that!'.format(text.lower()))

    return TYPING_REPLY


-def custom_choice(bot, update):
+def custom_choice(update, context):
    update.message.reply_text('Alright, please send me the category first, '
                              'for example "Most impressive skill"')

    return TYPING_CHOICE


-def received_information(bot, update, user_data):
+def received_information(update, context):
+    user_data = context.user_data
    text = update.message.text
    category = user_data['choice']
    user_data[category] = text
    del user_data['choice']

    update.message.reply_text("Neat! Just so you know, this is what you already told me:"
-                              "{}"
-                              "You can tell me more, or change your opinion on something.".format(
-                                  facts_to_str(user_data)), reply_markup=markup)
+                              "{} You can tell me more, or change your opinion"
+                              " on something.".format(facts_to_str(user_data)),
+                              reply_markup=markup)

    return CHOOSING


-def done(bot, update, user_data):
+def done(update, context):
+    user_data = context.user_data
    if 'choice' in user_data:
        del user_data['choice']

@@ -97,42 +100,41 @@ def done(bot, update, user_data):
    return ConversationHandler.END


-def error(bot, update, error):
+def error(update, context):
    """Log Errors caused by Updates."""
-    logger.warning('Update "%s" caused error "%s"', update, error)
+    logger.warning('Update "%s" caused error "%s"', update, context.error)


 def main():
    # Create the Updater and pass it your bot's token.
-    updater = Updater("TOKEN")
+    # Make sure to set use_context=True to use the new context based callbacks
+    # Post version 12 this will no longer be necessary
+    updater = Updater("TOKEN", use_context=True)

    # Get the dispatcher to register handlers
    dp = updater.dispatcher

-    # Add conversation handler with the states GENDER, PHOTO, LOCATION and BIO
+    # Add conversation handler with the states CHOOSING, TYPING_CHOICE and TYPING_REPLY
    conv_handler = ConversationHandler(
        entry_points=[CommandHandler('start', start)],

        states={
-            CHOOSING: [RegexHandler('^(Age|Favourite colour|Number of siblings)$',
-                                    regular_choice,
-                                    pass_user_data=True),
-                       RegexHandler('^Something else...$',
-                                    custom_choice),
+            CHOOSING: [MessageHandler(Filters.regex('^(Age|Favourite colour|Number of siblings)$'),
+                                      regular_choice),
+                       MessageHandler(Filters.regex('^Something else...$'),
+                                      custom_choice)
                       ],

            TYPING_CHOICE: [MessageHandler(Filters.text,
-                                           regular_choice,
-                                           pass_user_data=True),
+                                           regular_choice)
                            ],

            TYPING_REPLY: [MessageHandler(Filters.text,
-                                          received_information,
-                                          pass_user_data=True),
+                                          received_information),
                           ],
        },

-        fallbacks=[RegexHandler('^Done$', done, pass_user_data=True)]
+        fallbacks=[MessageHandler(Filters.regex('^Done$'), done)]
    )

    dp.add_handler(conv_handler)
@@ -1,11 +1,13 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
+# This program is dedicated to the public domain under the CC0 license.
+#
+# THIS EXAMPLE HAS BEEN UPDATED TO WORK WITH THE BETA VERSION 12 OF PYTHON-TELEGRAM-BOT.
+# If you're still using version 11.1.0, please see the examples at
+# https://github.com/python-telegram-bot/python-telegram-bot/tree/v11.1.0/examples

-"""Simple Bot to reply to Telegram messages.
-
-This program is dedicated to the public domain under the CC0 license.
-
-This Bot uses the Updater class to handle the bot.
+"""
+Simple Bot to reply to Telegram messages.

 First, a few handler functions are defined. Then, those functions are passed to
 the Dispatcher and registered at their respective places.
@@ -17,9 +19,10 @@ Press Ctrl-C on the command line or send a signal to the process to stop the
 bot.
 """

-from telegram.ext import Updater, CommandHandler, MessageHandler, Filters
 import logging

+from telegram.ext import Updater, CommandHandler, MessageHandler, Filters
+
 # Enable logging
 logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
                    level=logging.INFO)
@@ -29,30 +32,32 @@ logger = logging.getLogger(__name__)

 # Define a few command handlers. These usually take the two arguments bot and
 # update. Error handlers also receive the raised TelegramError object in error.
-def start(bot, update):
+def start(update, context):
    """Send a message when the command /start is issued."""
    update.message.reply_text('Hi!')


-def help(bot, update):
+def help(update, context):
    """Send a message when the command /help is issued."""
    update.message.reply_text('Help!')


-def echo(bot, update):
+def echo(update, context):
    """Echo the user message."""
    update.message.reply_text(update.message.text)


-def error(bot, update, error):
+def error(update, context):
    """Log Errors caused by Updates."""
-    logger.warning('Update "%s" caused error "%s"', update, error)
+    logger.warning('Update "%s" caused error "%s"', update, context.error)


 def main():
    """Start the bot."""
-    # Create the EventHandler and pass it your bot's token.
-    updater = Updater("TOKEN")
+    # Create the Updater and pass it your bot's token.
+    # Make sure to set use_context=True to use the new context based callbacks
+    # Post version 12 this will no longer be necessary
+    updater = Updater("TOKEN", use_context=True)

    # Get the dispatcher to register handlers
    dp = updater.dispatcher
@@ -1,12 +1,12 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
+# This program is dedicated to the public domain under the CC0 license.
+#
+# THIS EXAMPLE HAS BEEN UPDATED TO WORK WITH THE BETA VERSION 12 OF PYTHON-TELEGRAM-BOT.
+# If you're still using version 11.1.0, please see the examples at
+# https://github.com/python-telegram-bot/python-telegram-bot/tree/v11.1.0/examples

-"""Simple Bot to reply to Telegram messages.
-
-This program is dedicated to the public domain under the CC0 license.
-
-This Bot uses the Updater class to handle the bot.
-
+"""
 First, a few handler functions are defined. Then, those functions are passed to
 the Dispatcher and registered at their respective places.
 Then, the bot is started and runs until we press Ctrl-C on the command line.
@@ -16,14 +16,13 @@ Basic inline bot example. Applies different text transformations.
 Press Ctrl-C on the command line or send a signal to the process to stop the
 bot.
 """
+import logging
 from uuid import uuid4

-from telegram.utils.helpers import escape_markdown
-
 from telegram import InlineQueryResultArticle, ParseMode, \
    InputTextMessageContent
 from telegram.ext import Updater, InlineQueryHandler, CommandHandler
-import logging
+from telegram.utils.helpers import escape_markdown

 # Enable logging
 logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
@@ -34,17 +33,17 @@ logger = logging.getLogger(__name__)

 # Define a few command handlers. These usually take the two arguments bot and
 # update. Error handlers also receive the raised TelegramError object in error.
-def start(bot, update):
+def start(update, context):
    """Send a message when the command /start is issued."""
    update.message.reply_text('Hi!')


-def help(bot, update):
+def help(update, context):
    """Send a message when the command /help is issued."""
    update.message.reply_text('Help!')


-def inlinequery(bot, update):
+def inlinequery(update, context):
    """Handle the inline query."""
    query = update.inline_query.query
    results = [
@@ -69,14 +68,16 @@ def inlinequery(bot, update):
    update.inline_query.answer(results)


-def error(bot, update, error):
+def error(update, context):
    """Log Errors caused by Updates."""
-    logger.warning('Update "%s" caused error "%s"', update, error)
+    logger.warning('Update "%s" caused error "%s"', update, context.error)


 def main():
    # Create the Updater and pass it your bot's token.
-    updater = Updater("TOKEN")
+    # Make sure to set use_context=True to use the new context based callbacks
+    # Post version 12 this will no longer be necessary
+    updater = Updater("TOKEN", use_context=True)

    # Get the dispatcher to register handlers
    dp = updater.dispatcher
@@ -1,10 +1,16 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-"""Basic example for a bot that uses inline keyboards.
-
 # This program is dedicated to the public domain under the CC0 license.
+#
+# THIS EXAMPLE HAS BEEN UPDATED TO WORK WITH THE BETA VERSION 12 OF PYTHON-TELEGRAM-BOT.
+# If you're still using version 11.1.0, please see the examples at
+# https://github.com/python-telegram-bot/python-telegram-bot/tree/v11.1.0/examples
+
+"""
+Basic example for a bot that uses inline keyboards.
 """
 import logging
+
 from telegram import InlineKeyboardButton, InlineKeyboardMarkup
 from telegram.ext import Updater, CommandHandler, CallbackQueryHandler

@@ -13,7 +19,7 @@ logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s
 logger = logging.getLogger(__name__)


-def start(bot, update):
+def start(update, context):
    keyboard = [[InlineKeyboardButton("Option 1", callback_data='1'),
                 InlineKeyboardButton("Option 2", callback_data='2')],

@@ -24,26 +30,26 @@ def start(bot, update):
    update.message.reply_text('Please choose:', reply_markup=reply_markup)


-def button(bot, update):
+def button(update, context):
    query = update.callback_query

-    bot.edit_message_text(text="Selected option: {}".format(query.data),
-                          chat_id=query.message.chat_id,
-                          message_id=query.message.message_id)
+    query.edit_message_text(text="Selected option: {}".format(query.data))


-def help(bot, update):
+def help(update, context):
    update.message.reply_text("Use /start to test this bot.")


-def error(bot, update, error):
+def error(update, context):
    """Log Errors caused by Updates."""
-    logger.warning('Update "%s" caused error "%s"', update, error)
+    logger.warning('Update "%s" caused error "%s"', update, context.error)


 def main():
    # Create the Updater and pass it your bot's token.
-    updater = Updater("TOKEN")
+    # Make sure to set use_context=True to use the new context based callbacks
+    # Post version 12 this will no longer be necessary
+    updater = Updater("TOKEN", use_context=True)

    updater.dispatcher.add_handler(CommandHandler('start', start))
    updater.dispatcher.add_handler(CallbackQueryHandler(button))
@@ -1,9 +1,14 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-#
-# Simple Bot to print/download all incoming passport data
 # This program is dedicated to the public domain under the CC0 license.
+#
+# THIS EXAMPLE HAS BEEN UPDATED TO WORK WITH THE BETA VERSION 12 OF PYTHON-TELEGRAM-BOT.
+# If you're still using version 11.1.0, please see the examples at
+# https://github.com/python-telegram-bot/python-telegram-bot/tree/v11.1.0/examples
+
 """
+Simple Bot to print/download all incoming passport data
+
 See https://telegram.org/blog/passport for info about what telegram passport is.

 See https://git.io/fAvYd for how to use Telegram Passport properly with python-telegram-bot.
@@ -1,15 +1,20 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
+# This program is dedicated to the public domain under the CC0 license.
 #
-"""Basic example for a bot that can receive payment from user.
+# THIS EXAMPLE HAS BEEN UPDATED TO WORK WITH THE BETA VERSION 12 OF PYTHON-TELEGRAM-BOT.
+# If you're still using version 11.1.0, please see the examples at
+# https://github.com/python-telegram-bot/python-telegram-bot/tree/v11.1.0/examples

-This program is dedicated to the public domain under the CC0 license.
 """
+Basic example for a bot that can receive payment from user.
+"""
+
+import logging

 from telegram import (LabeledPrice, ShippingOption)
 from telegram.ext import (Updater, CommandHandler, MessageHandler,
                          Filters, PreCheckoutQueryHandler, ShippingQueryHandler)
-import logging

 # Enable logging
 logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
@@ -18,18 +23,18 @@ logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s
 logger = logging.getLogger(__name__)


-def error(bot, update, error):
+def error(update, context):
    """Log Errors caused by Updates."""
-    logger.warning('Update "%s" caused error "%s"', update, error)
+    logger.warning('Update "%s" caused error "%s"', update, context.error)


-def start_callback(bot, update):
+def start_callback(update, context):
    msg = "Use /shipping to get an invoice for shipping-payment, "
    msg += "or /noshipping for an invoice without shipping."
    update.message.reply_text(msg)


-def start_with_shipping_callback(bot, update):
+def start_with_shipping_callback(update, context):
    chat_id = update.message.chat_id
    title = "Payment Example"
    description = "Payment Example using python-telegram-bot"
@@ -47,13 +52,13 @@ def start_with_shipping_callback(bot, update):

    # optionally pass need_name=True, need_phone_number=True,
    # need_email=True, need_shipping_address=True, is_flexible=True
-    bot.sendInvoice(chat_id, title, description, payload,
-                    provider_token, start_parameter, currency, prices,
-                    need_name=True, need_phone_number=True,
-                    need_email=True, need_shipping_address=True, is_flexible=True)
+    context.bot.send_invoice(chat_id, title, description, payload,
+                             provider_token, start_parameter, currency, prices,
+                             need_name=True, need_phone_number=True,
+                             need_email=True, need_shipping_address=True, is_flexible=True)


-def start_without_shipping_callback(bot, update):
+def start_without_shipping_callback(update, context):
    chat_id = update.message.chat_id
    title = "Payment Example"
    description = "Payment Example using python-telegram-bot"
@@ -70,17 +75,16 @@ def start_without_shipping_callback(bot, update):

    # optionally pass need_name=True, need_phone_number=True,
    # need_email=True, need_shipping_address=True, is_flexible=True
-    bot.sendInvoice(chat_id, title, description, payload,
-                    provider_token, start_parameter, currency, prices)
+    context.bot.send_invoice(chat_id, title, description, payload,
+                             provider_token, start_parameter, currency, prices)


-def shipping_callback(bot, update):
+def shipping_callback(update, context):
    query = update.shipping_query
    # check the payload, is this from your bot?
    if query.invoice_payload != 'Custom-Payload':
        # answer False pre_checkout_query
-        bot.answer_shipping_query(shipping_query_id=query.id, ok=False,
-                                  error_message="Something went wrong...")
+        query.answer(ok=False, error_message="Something went wrong...")
        return
    else:
        options = list()
@@ -89,31 +93,31 @@ def shipping_callback(bot, update):
        # an array of LabeledPrice objects
        price_list = [LabeledPrice('B1', 150), LabeledPrice('B2', 200)]
        options.append(ShippingOption('2', 'Shipping Option B', price_list))
-        bot.answer_shipping_query(shipping_query_id=query.id, ok=True,
-                                  shipping_options=options)
+        query.answer(ok=True, shipping_options=options)


 # after (optional) shipping, it's the pre-checkout
-def precheckout_callback(bot, update):
+def precheckout_callback(update, context):
    query = update.pre_checkout_query
    # check the payload, is this from your bot?
    if query.invoice_payload != 'Custom-Payload':
        # answer False pre_checkout_query
-        bot.answer_pre_checkout_query(pre_checkout_query_id=query.id, ok=False,
-                                      error_message="Something went wrong...")
+        query.answer(ok=False, error_message="Something went wrong...")
    else:
-        bot.answer_pre_checkout_query(pre_checkout_query_id=query.id, ok=True)
+        query.answer(ok=True)


 # finally, after contacting to the payment provider...
-def successful_payment_callback(bot, update):
+def successful_payment_callback(update, context):
    # do something after successful receive of payment?
    update.message.reply_text("Thank you for your payment!")


 def main():
-    # Create the EventHandler and pass it your bot's token.
-    updater = Updater(token="BOT_TOKEN")
+    # Create the Updater and pass it your bot's token.
+    # Make sure to set use_context=True to use the new context based callbacks
+    # Post version 12 this will no longer be necessary
+    updater = Updater("TOKEN", use_context=True)

    # Get the dispatcher to register handlers
    dp = updater.dispatcher
@@ -0,0 +1,169 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# This program is dedicated to the public domain under the CC0 license.
+#
+# THIS EXAMPLE HAS BEEN UPDATED TO WORK WITH THE BETA VERSION 12 OF PYTHON-TELEGRAM-BOT.
+# If you're still using version 11.1.0, please see the examples at
+# https://github.com/python-telegram-bot/python-telegram-bot/tree/v11.1.0/examples
+
+"""
+First, a few callback functions are defined. Then, those functions are passed to
+the Dispatcher and registered at their respective places.
+Then, the bot is started and runs until we press Ctrl-C on the command line.
+
+Usage:
+Example of a bot-user conversation using ConversationHandler.
+Send /start to initiate the conversation.
+Press Ctrl-C on the command line or send a signal to the process to stop the
+bot.
+"""
+
+from telegram import ReplyKeyboardMarkup
+from telegram.ext import (Updater, CommandHandler, MessageHandler, Filters,
+                          ConversationHandler, PicklePersistence)
+
+import logging
+
+# Enable logging
+logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+                    level=logging.INFO)
+
+logger = logging.getLogger(__name__)
+
+CHOOSING, TYPING_REPLY, TYPING_CHOICE = range(3)
+
+reply_keyboard = [['Age', 'Favourite colour'],
+                  ['Number of siblings', 'Something else...'],
+                  ['Done']]
+markup = ReplyKeyboardMarkup(reply_keyboard, one_time_keyboard=True)
+
+
+def facts_to_str(user_data):
+    facts = list()
+
+    for key, value in user_data.items():
+        facts.append('{} - {}'.format(key, value))
+
+    return "\n".join(facts).join(['\n', '\n'])
+
+
+def start(update, context):
+    reply_text = "Hi! My name is Doctor Botter."
+    if context.user_data:
+        reply_text += " You already told me your {}. Why don't you tell me something more " \
+                      "about yourself? Or change enything I " \
+                      "already know.".format(", ".join(context.user_data.keys()))
+    else:
+        reply_text += " I will hold a more complex conversation with you. Why don't you tell me " \
+                      "something about yourself?"
+    update.message.reply_text(reply_text, reply_markup=markup)
+
+    return CHOOSING
+
+
+def regular_choice(update, context):
+    text = update.message.text.lower()
+    context.user_data['choice'] = text
+    if context.user_data.get(text):
+        reply_text = 'Your {}, I already know the following ' \
+                     'about that: {}'.format(text, context.user_data[text])
+    else:
+        reply_text = 'Your {}? Yes, I would love to hear about that!'.format(text)
+    update.message.reply_text(reply_text)
+
+    return TYPING_REPLY
+
+
+def custom_choice(update, context):
+    update.message.reply_text('Alright, please send me the category first, '
+                              'for example "Most impressive skill"')
+
+    return TYPING_CHOICE
+
+
+def received_information(update, context):
+    text = update.message.text
+    category = context.user_data['choice']
+    context.user_data[category] = text.lower()
+    del context.user_data['choice']
+
+    update.message.reply_text("Neat! Just so you know, this is what you already told me:"
+                              "{}"
+                              "You can tell me more, or change your opinion on "
+                              "something.".format(facts_to_str(context.user_data)),
+                              reply_markup=markup)
+
+    return CHOOSING
+
+
+def show_data(update, context):
+    update.message.reply_text("This is what you already told me:"
+                              "{}".format(facts_to_str(context.user_data)))
+
+
+def done(update, context):
+    if 'choice' in context.user_data:
+        del context.user_data['choice']
+
+    update.message.reply_text("I learned these facts about you:"
+                              "{}"
+                              "Until next time!".format(facts_to_str(context.user_data)))
+    return ConversationHandler.END
+
+
+def error(update, context):
+    """Log Errors caused by Updates."""
+    logger.warning('Update "%s" caused error "%s"', update, context.error)
+
+
+def main():
+    # Create the Updater and pass it your bot's token.
+    pp = PicklePersistence(filename='conversationbot')
+    updater = Updater("TOKEN", persistence=pp, use_context=True)
+
+    # Get the dispatcher to register handlers
+    dp = updater.dispatcher
+
+    # Add conversation handler with the states CHOOSING, TYPING_CHOICE and TYPING_REPLY
+    conv_handler = ConversationHandler(
+        entry_points=[CommandHandler('start', start)],
+
+        states={
+            CHOOSING: [MessageHandler(Filters.regex('^(Age|Favourite colour|Number of siblings)$'),
+                                      regular_choice),
+                       MessageHandler(Filters.regex('^Something else...$'),
+                                      custom_choice),
+                       ],
+
+            TYPING_CHOICE: [MessageHandler(Filters.text,
+                                           regular_choice),
+                            ],
+
+            TYPING_REPLY: [MessageHandler(Filters.text,
+                                          received_information),
+                           ],
+        },
+
+        fallbacks=[MessageHandler(Filters.regex('^Done$'), done)],
+        name="my_conversation",
+        persistent=True
+    )
+
+    dp.add_handler(conv_handler)
+
+    show_data_handler = CommandHandler('show_data', show_data)
+    dp.add_handler(show_data_handler)
+    # log all errors
+    dp.add_error_handler(error)
+
+    # Start the Bot
+    updater.start_polling()
+
+    # Run the bot until you press Ctrl-C or the process receives SIGINT,
+    # SIGTERM or SIGABRT. This should be used most of the time, since
+    # start_polling() is non-blocking and will stop the bot gracefully.
+    updater.idle()
+
+
+if __name__ == '__main__':
+    main()
@@ -1,10 +1,13 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-
-
-"""Simple Bot to send timed Telegram messages.
-
 # This program is dedicated to the public domain under the CC0 license.
+#
+# THIS EXAMPLE HAS BEEN UPDATED TO WORK WITH THE BETA VERSION 12 OF PYTHON-TELEGRAM-BOT.
+# If you're still using version 11.1.0, please see the examples at
+# https://github.com/python-telegram-bot/python-telegram-bot/tree/v11.1.0/examples
+
+"""
+Simple Bot to send timed Telegram messages.

 This Bot uses the Updater class to handle the bot and the JobQueue to send
 timed messages.
@@ -19,9 +22,10 @@ Press Ctrl-C on the command line or send a signal to the process to stop the
 bot.
 """

-from telegram.ext import Updater, CommandHandler
 import logging

+from telegram.ext import Updater, CommandHandler
+
 # Enable logging
 logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
                    level=logging.INFO)
@@ -31,28 +35,32 @@ logger = logging.getLogger(__name__)

 # Define a few command handlers. These usually take the two arguments bot and
 # update. Error handlers also receive the raised TelegramError object in error.
-def start(bot, update):
+def start(update, context):
    update.message.reply_text('Hi! Use /set <seconds> to set a timer')


-def alarm(bot, job):
+def alarm(context):
    """Send the alarm message."""
-    bot.send_message(job.context, text='Beep!')
+    job = context.job
+    context.bot.send_message(job.context, text='Beep!')


-def set_timer(bot, update, args, job_queue, chat_data):
+def set_timer(update, context):
    """Add a job to the queue."""
    chat_id = update.message.chat_id
    try:
        # args[0] should contain the time for the timer in seconds
-        due = int(args[0])
+        due = int(context.args[0])
        if due < 0:
            update.message.reply_text('Sorry we can not go back to future!')
            return

-        # Add job to queue
-        job = job_queue.run_once(alarm, due, context=chat_id)
-        chat_data['job'] = job
+        # Add job to queue and stop current one if there is a timer already
+        if 'job' in context.chat_data:
+            old_job = context.chat_data['job']
+            old_job.schedule_removal()
+        new_job = context.job_queue.run_once(alarm, due, context=chat_id)
+        context.chat_data['job'] = new_job

        update.message.reply_text('Timer successfully set!')

@@ -60,27 +68,30 @@ def set_timer(bot, update, args, job_queue, chat_data):
        update.message.reply_text('Usage: /set <seconds>')


-def unset(bot, update, chat_data):
+def unset(update, context):
    """Remove the job if the user changed their mind."""
-    if 'job' not in chat_data:
+    if 'job' not in context.chat_data:
        update.message.reply_text('You have no active timer')
        return

-    job = chat_data['job']
+    job = context.chat_data['job']
    job.schedule_removal()
-    del chat_data['job']
+    del context.chat_data['job']

    update.message.reply_text('Timer successfully unset!')


-def error(bot, update, error):
+def error(update, context):
    """Log Errors caused by Updates."""
-    logger.warning('Update "%s" caused error "%s"', update, error)
+    logger.warning('Update "%s" caused error "%s"', update, context.error)


 def main():
    """Run bot."""
-    updater = Updater("TOKEN")
+    # Create the Updater and pass it your bot's token.
+    # Make sure to set use_context=True to use the new context based callbacks
+    # Post version 12 this will no longer be necessary
+    updater = Updater("TOKEN", use_context=True)

    # Get the dispatcher to register handlers
    dp = updater.dispatcher
@@ -5,6 +5,6 @@ flaky
 yapf
 pre-commit
 beautifulsoup4
-pytest
+pytest==4.2.0
 pytest-timeout
 wheel
@@ -1,3 +1,4 @@
 future>=0.16.0
 certifi
+tornado>=5.1
 cryptography
@@ -27,6 +27,7 @@ addopts = --no-success-flaky-report -rsxX
 filterwarnings =
    error
    ignore::DeprecationWarning
+    ignore::telegram.utils.deprecate.TelegramDeprecationWarning

 [coverage:run]
 branch = True
@@ -55,5 +55,6 @@ with codecs.open('README.rst', 'r', 'utf-8') as fd:
              'Programming Language :: Python :: 3',
              'Programming Language :: Python :: 3.4',
              'Programming Language :: Python :: 3.5',
-              'Programming Language :: Python :: 3.6'
+              'Programming Language :: Python :: 3.6',
+              'Programming Language :: Python :: 3.7'
          ],)
@@ -1,4 +1,4 @@
-''#!/usr/bin/env python
+#!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
 # Copyright (C) 2015-2018
@@ -47,6 +47,8 @@ from .files.file import File
 from .parsemode import ParseMode
 from .messageentity import MessageEntity
 from .games.game import Game
+from .poll import Poll, PollOption
+from .loginurl import LoginUrl
 from .games.callbackgame import CallbackGame
 from .payment.shippingaddress import ShippingAddress
 from .payment.orderinfo import OrderInfo
@@ -57,11 +59,11 @@ from .passport.passportfile import PassportFile
 from .passport.data import IdDocumentData, PersonalDetails, ResidentialAddress
 from .passport.encryptedpassportelement import EncryptedPassportElement
 from .passport.passportdata import PassportData
+from .inline.inlinekeyboardbutton import InlineKeyboardButton
+from .inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from .message import Message
 from .callbackquery import CallbackQuery
 from .choseninlineresult import ChosenInlineResult
-from .inline.inlinekeyboardbutton import InlineKeyboardButton
-from .inline.inlinekeyboardmarkup import InlineKeyboardMarkup
 from .inline.inputmessagecontent import InputMessageContent
 from .inline.inlinequery import InlineQuery
 from .inline.inlinequeryresult import InlineQueryResult
@@ -118,7 +120,7 @@ from .passport.credentials import (Credentials,
                                   SecureData,
                                   FileCredentials,
                                   TelegramDecryptionError)
-from .version import __version__  # flake8: noqa
+from .version import __version__  # noqa: F401

 __author__ = 'devs@python-telegram-bot.org'

@@ -152,5 +154,6 @@ __all__ = [
    'PersonalDetails', 'ResidentialAddress', 'InputMediaVideo', 'InputMediaAnimation',
    'InputMediaAudio', 'InputMediaDocument', 'TelegramDecryptionError',
    'PassportElementErrorSelfie', 'PassportElementErrorTranslationFile',
-    'PassportElementErrorTranslationFiles', 'PassportElementErrorUnspecified'
+    'PassportElementErrorTranslationFiles', 'PassportElementErrorUnspecified', 'Poll',
+    'PollOption', 'LoginUrl'
 ]
@@ -17,15 +17,28 @@
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 import sys
+import subprocess

 import certifi
 import future

+
 from . import __version__ as telegram_ver


+def _git_revision():
+    try:
+        output = subprocess.check_output(["git", "describe", "--long", "--tags"],
+                                         stderr=subprocess.STDOUT)
+    except (subprocess.SubprocessError, OSError):
+        return None
+    return output.decode().strip()
+
+
 def print_ver_info():
-    print('python-telegram-bot {0}'.format(telegram_ver))
+    git_revision = _git_revision()
+    print('python-telegram-bot {0}'.format(telegram_ver) + (' ({0})'.format(git_revision)
+                                                            if git_revision else ''))
    print('certifi {0}'.format(certifi.__version__))
    print('future {0}'.format(future.__version__))
    print('Python {0}'.format(sys.version.replace('\n', ' ')))
@@ -21,6 +21,7 @@
 """This module contains an object that represents a Telegram Bot."""

 import functools
+
 try:
    import ujson as json
 except ImportError:
@@ -36,7 +37,7 @@ from future.utils import string_types
 from telegram import (User, Message, Update, Chat, ChatMember, UserProfilePhotos, File,
                      ReplyMarkup, TelegramObject, WebhookInfo, GameHighScore, StickerSet,
                      PhotoSize, Audio, Document, Sticker, Video, Animation, Voice, VideoNote,
-                      Location, Venue, Contact, InputFile)
+                      Location, Venue, Contact, InputFile, Poll)
 from telegram.error import InvalidToken, TelegramError
 from telegram.utils.helpers import to_timestamp
 from telegram.utils.request import Request
@@ -70,33 +71,6 @@ def log(func):
    return decorator


-def message(func):
-    @functools.wraps(func)
-    def decorator(self, *args, **kwargs):
-        url, data = func(self, *args, **kwargs)
-        if kwargs.get('reply_to_message_id'):
-            data['reply_to_message_id'] = kwargs.get('reply_to_message_id')
-
-        if kwargs.get('disable_notification'):
-            data['disable_notification'] = kwargs.get('disable_notification')
-
-        if kwargs.get('reply_markup'):
-            reply_markup = kwargs.get('reply_markup')
-            if isinstance(reply_markup, ReplyMarkup):
-                data['reply_markup'] = reply_markup.to_json()
-            else:
-                data['reply_markup'] = reply_markup
-
-        result = self._request.post(url, data, timeout=kwargs.get('timeout'))
-
-        if result is True:
-            return result
-
-        return Message.de_json(result, self)
-
-    return decorator
-
-
 class Bot(TelegramObject):
    """This object represents a Telegram Bot.

@@ -132,6 +106,27 @@ class Bot(TelegramObject):
                                                                  password=private_key_password,
                                                                  backend=default_backend())

+    def _message(self, url, data, reply_to_message_id=None, disable_notification=None,
+                 reply_markup=None, timeout=None, **kwargs):
+        if reply_to_message_id is not None:
+            data['reply_to_message_id'] = reply_to_message_id
+
+        if disable_notification is not None:
+            data['disable_notification'] = disable_notification
+
+        if reply_markup is not None:
+            if isinstance(reply_markup, ReplyMarkup):
+                data['reply_markup'] = reply_markup.to_json()
+            else:
+                data['reply_markup'] = reply_markup
+
+        result = self._request.post(url, data, timeout=timeout)
+
+        if result is True:
+            return result
+
+        return Message.de_json(result, self)
+
    @property
    def request(self):
        return self._request
@@ -208,7 +203,6 @@ class Bot(TelegramObject):
        return self.bot

    @log
-    @message
    def send_message(self,
                     chat_id,
                     text,
@@ -259,18 +253,23 @@ class Bot(TelegramObject):
        if disable_web_page_preview:
            data['disable_web_page_preview'] = disable_web_page_preview

-        return url, data
+        return self._message(url, data, disable_notification=disable_notification,
+                             reply_to_message_id=reply_to_message_id, reply_markup=reply_markup,
+                             timeout=timeout, **kwargs)

    @log
    def delete_message(self, chat_id, message_id, timeout=None, **kwargs):
        """
-        Use this method to delete a message. A message can only be deleted if it was sent less
-        than 48 hours ago. Any such recently sent outgoing message may be deleted. Additionally,
-        if the bot is an administrator in a group chat, it can delete any message. If the bot is
-        an administrator in a supergroup, it can delete messages from any other user and service
-        messages about people joining or leaving the group (other types of service messages may
-        only be removed by the group creator). In channels, bots can only remove their own
-        messages.
+        Use this method to delete a message, including service messages, with the following
+        limitations:
+
+            - A message can only be deleted if it was sent less than 48 hours ago.
+            - Bots can delete outgoing messages in private chats, groups, and supergroups.
+            - Bots can delete incoming messages in private chats.
+            - Bots granted can_post_messages permissions can delete outgoing messages in channels.
+            - If the bot is an administrator of a group, it can delete any message there.
+            - If the bot has can_delete_messages permission in a supergroup or a channel, it can
+              delete any message there.

        Args:
            chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
@@ -298,7 +297,6 @@ class Bot(TelegramObject):
        return result

    @log
-    @message
    def forward_message(self,
                        chat_id,
                        from_chat_id,
@@ -340,10 +338,10 @@ class Bot(TelegramObject):
        if message_id:
            data['message_id'] = message_id

-        return url, data
+        return self._message(url, data, disable_notification=disable_notification,
+                             timeout=timeout, **kwargs)

    @log
-    @message
    def send_photo(self,
                   chat_id,
                   photo,
@@ -369,7 +367,7 @@ class Bot(TelegramObject):
                Internet, or upload a new photo using multipart/form-data. Lastly you can pass
                an existing :class:`telegram.PhotoSize` object to send.
            caption (:obj:`str`, optional): Photo caption (may also be used when resending photos
-                by file_id), 0-200 characters.
+                by file_id), 0-1024 characters.
            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.
@@ -404,10 +402,11 @@ class Bot(TelegramObject):
        if parse_mode:
            data['parse_mode'] = parse_mode

-        return url, data
+        return self._message(url, data, timeout=timeout, disable_notification=disable_notification,
+                             reply_to_message_id=reply_to_message_id, reply_markup=reply_markup,
+                             **kwargs)

    @log
-    @message
    def send_audio(self,
                   chat_id,
                   audio,
@@ -442,7 +441,7 @@ class Bot(TelegramObject):
                (recommended), pass an HTTP URL as a String for Telegram to get an audio file from
                the Internet, or upload a new one using multipart/form-data. Lastly you can pass
                an existing :class:`telegram.Audio` object to send.
-            caption (:obj:`str`, optional): Audio caption, 0-200 characters.
+            caption (:obj:`str`, optional): Audio caption, 0-1024 characters.
            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.
@@ -494,10 +493,11 @@ class Bot(TelegramObject):
                thumb = InputFile(thumb, attach=True)
            data['thumb'] = thumb

-        return url, data
+        return self._message(url, data, timeout=timeout, disable_notification=disable_notification,
+                             reply_to_message_id=reply_to_message_id, reply_markup=reply_markup,
+                             **kwargs)

    @log
-    @message
    def send_document(self,
                      chat_id,
                      document,
@@ -527,7 +527,7 @@ class Bot(TelegramObject):
            filename (:obj:`str`, optional): File name that shows in telegram message (it is useful
                when you send file generated by temp module, for example). Undocumented.
            caption (:obj:`str`, optional): Document caption (may also be used when resending
-                documents by file_id), 0-200 characters.
+                documents by file_id), 0-1024 characters.
            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.
@@ -570,10 +570,11 @@ class Bot(TelegramObject):
                thumb = InputFile(thumb, attach=True)
            data['thumb'] = thumb

-        return url, data
+        return self._message(url, data, timeout=timeout, disable_notification=disable_notification,
+                             reply_to_message_id=reply_to_message_id, reply_markup=reply_markup,
+                             **kwargs)

    @log
-    @message
    def send_sticker(self,
                     chat_id,
                     sticker,
@@ -622,10 +623,11 @@ class Bot(TelegramObject):

        data = {'chat_id': chat_id, 'sticker': sticker}

-        return url, data
+        return self._message(url, data, timeout=timeout, disable_notification=disable_notification,
+                             reply_to_message_id=reply_to_message_id, reply_markup=reply_markup,
+                             **kwargs)

    @log
-    @message
    def send_video(self,
                   chat_id,
                   video,
@@ -661,7 +663,7 @@ class Bot(TelegramObject):
            width (:obj:`int`, optional): Video width.
            height (:obj:`int`, optional): Video height.
            caption (:obj:`str`, optional): Video caption (may also be used when resending videos
-                by file_id), 0-200 characters.
+                by file_id), 0-1024 characters.
            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.
@@ -714,10 +716,11 @@ class Bot(TelegramObject):
                thumb = InputFile(thumb, attach=True)
            data['thumb'] = thumb

-        return url, data
+        return self._message(url, data, timeout=timeout, disable_notification=disable_notification,
+                             reply_to_message_id=reply_to_message_id, reply_markup=reply_markup,
+                             **kwargs)

    @log
-    @message
    def send_video_note(self,
                        chat_id,
                        video_note,
@@ -784,10 +787,11 @@ class Bot(TelegramObject):
                thumb = InputFile(thumb, attach=True)
            data['thumb'] = thumb

-        return url, data
+        return self._message(url, data, timeout=timeout, disable_notification=disable_notification,
+                             reply_to_message_id=reply_to_message_id, reply_markup=reply_markup,
+                             **kwargs)

    @log
-    @message
    def send_animation(self,
                       chat_id,
                       animation,
@@ -821,7 +825,7 @@ class Bot(TelegramObject):
                A thumbnail's width and height should not exceed 90. Ignored if the file is not
                is passed as a string or file_id.
            caption (:obj:`str`, optional): Animation caption (may also be used when resending
-                animations by file_id), 0-200 characters.
+                animations by file_id), 0-1024 characters.
            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.
@@ -866,10 +870,11 @@ class Bot(TelegramObject):
        if parse_mode:
            data['parse_mode'] = parse_mode

-        return url, data
+        return self._message(url, data, timeout=timeout, disable_notification=disable_notification,
+                             reply_to_message_id=reply_to_message_id, reply_markup=reply_markup,
+                             **kwargs)

    @log
-    @message
    def send_voice(self,
                   chat_id,
                   voice,
@@ -898,7 +903,7 @@ class Bot(TelegramObject):
                (recommended), pass an HTTP URL as a String for Telegram to get an voice file from
                the Internet, or upload a new one using multipart/form-data. Lastly you can pass
                an existing :class:`telegram.Voice` object to send.
-            caption (:obj:`str`, optional): Voice message caption, 0-200 characters.
+            caption (:obj:`str`, optional): Voice message caption, 0-1024 characters.
            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.
@@ -936,7 +941,9 @@ class Bot(TelegramObject):
        if parse_mode:
            data['parse_mode'] = parse_mode

-        return url, data
+        return self._message(url, data, timeout=timeout, disable_notification=disable_notification,
+                             reply_to_message_id=reply_to_message_id, reply_markup=reply_markup,
+                             **kwargs)

    @log
    def send_media_group(self,
@@ -981,7 +988,6 @@ class Bot(TelegramObject):
        return [Message.de_json(res, self) for res in result]

    @log
-    @message
    def send_location(self,
                      chat_id,
                      latitude=None,
@@ -1027,7 +1033,7 @@ class Bot(TelegramObject):
        """
        url = '{0}/sendLocation'.format(self.base_url)

-        if not (all([latitude, longitude]) or location):
+        if not ((latitude is not None and longitude is not None) or location):
            raise ValueError("Either location or latitude and longitude must be passed as"
                             "argument.")

@@ -1044,10 +1050,11 @@ class Bot(TelegramObject):
        if live_period:
            data['live_period'] = live_period

-        return url, data
+        return self._message(url, data, timeout=timeout, disable_notification=disable_notification,
+                             reply_to_message_id=reply_to_message_id, reply_markup=reply_markup,
+                             **kwargs)

    @log
-    @message
    def edit_message_live_location(self,
                                   chat_id=None,
                                   message_id=None,
@@ -1056,6 +1063,7 @@ class Bot(TelegramObject):
                                   longitude=None,
                                   location=None,
                                   reply_markup=None,
+                                   timeout=None,
                                   **kwargs):
        """Use this method to edit live location messages sent by the bot or via the bot
        (for inline bots). A location can be edited until its :attr:`live_period` expires or
@@ -1107,15 +1115,15 @@ class Bot(TelegramObject):
        if inline_message_id:
            data['inline_message_id'] = inline_message_id

-        return url, data
+        return self._message(url, data, timeout=timeout, reply_markup=reply_markup, **kwargs)

    @log
-    @message
    def stop_message_live_location(self,
                                   chat_id=None,
                                   message_id=None,
                                   inline_message_id=None,
                                   reply_markup=None,
+                                   timeout=None,
                                   **kwargs):
        """Use this method to stop updating a live location message sent by the bot or via the bot
        (for inline bots) before live_period expires.
@@ -1149,10 +1157,9 @@ class Bot(TelegramObject):
        if inline_message_id:
            data['inline_message_id'] = inline_message_id

-        return url, data
+        return self._message(url, data, timeout=timeout, reply_markup=reply_markup, **kwargs)

    @log
-    @message
    def send_venue(self,
                   chat_id,
                   latitude=None,
@@ -1232,10 +1239,11 @@ class Bot(TelegramObject):
        if foursquare_type:
            data['foursquare_type'] = foursquare_type

-        return url, data
+        return self._message(url, data, timeout=timeout, disable_notification=disable_notification,
+                             reply_to_message_id=reply_to_message_id, reply_markup=reply_markup,
+                             **kwargs)

    @log
-    @message
    def send_contact(self,
                     chat_id,
                     phone_number=None,
@@ -1301,10 +1309,11 @@ class Bot(TelegramObject):
        if vcard:
            data['vcard'] = vcard

-        return url, data
+        return self._message(url, data, timeout=timeout, disable_notification=disable_notification,
+                             reply_to_message_id=reply_to_message_id, reply_markup=reply_markup,
+                             **kwargs)

    @log
-    @message
    def send_game(self,
                  chat_id,
                  game_short_name,
@@ -1343,7 +1352,9 @@ class Bot(TelegramObject):

        data = {'chat_id': chat_id, 'game_short_name': game_short_name}

-        return url, data
+        return self._message(url, data, timeout=timeout, disable_notification=disable_notification,
+                             reply_to_message_id=reply_to_message_id, reply_markup=reply_markup,
+                             **kwargs)

    @log
    def send_chat_action(self, chat_id, action, timeout=None, **kwargs):
@@ -1677,7 +1688,6 @@ class Bot(TelegramObject):
        return result

    @log
-    @message
    def edit_message_text(self,
                          text,
                          chat_id=None,
@@ -1736,10 +1746,9 @@ class Bot(TelegramObject):
        if disable_web_page_preview:
            data['disable_web_page_preview'] = disable_web_page_preview

-        return url, data
+        return self._message(url, data, timeout=timeout, reply_markup=reply_markup, **kwargs)

    @log
-    @message
    def edit_message_caption(self,
                             chat_id=None,
                             message_id=None,
@@ -1755,7 +1764,7 @@ class Bot(TelegramObject):

        Args:
            chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
-                of the target`channel (in the format @channelusername).
+                of the target channel (in the format @channelusername).
            message_id (:obj:`int`, optional): Required if inline_message_id is not specified.
                Identifier of the sent message.
            inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not
@@ -1800,10 +1809,9 @@ class Bot(TelegramObject):
        if inline_message_id:
            data['inline_message_id'] = inline_message_id

-        return url, data
+        return self._message(url, data, timeout=timeout, reply_markup=reply_markup, **kwargs)

    @log
-    @message
    def edit_message_media(self,
                           chat_id=None,
                           message_id=None,
@@ -1821,7 +1829,7 @@ class Bot(TelegramObject):

        Args:
            chat_id (:obj:`int` | :obj:`str`, optional): Unique identifier for the target chat or
-                username of the target`channel (in the format @channelusername).
+                username of the target channel (in the format @channelusername).
            message_id (:obj:`int`, optional): Required if inline_message_id is not specified.
                Identifier of the sent message.
            inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not
@@ -1853,10 +1861,9 @@ class Bot(TelegramObject):
        if inline_message_id:
            data['inline_message_id'] = inline_message_id

-        return url, data
+        return self._message(url, data, timeout=timeout, reply_markup=reply_markup, **kwargs)

    @log
-    @message
    def edit_message_reply_markup(self,
                                  chat_id=None,
                                  message_id=None,
@@ -1870,7 +1877,7 @@ class Bot(TelegramObject):

        Args:
            chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
-                of the target`channel (in the format @channelusername).
+                of the target channel (in the format @channelusername).
            message_id (:obj:`int`, optional): Required if inline_message_id is not specified.
                Identifier of the sent message.
            inline_message_id (:obj:`str`, optional): Required if chat_id and message_id are not
@@ -1907,7 +1914,7 @@ class Bot(TelegramObject):
        if inline_message_id:
            data['inline_message_id'] = inline_message_id

-        return url, data
+        return self._message(url, data, timeout=timeout, reply_markup=reply_markup, **kwargs)

    @log
    def get_updates(self,
@@ -2104,7 +2111,7 @@ class Bot(TelegramObject):

        Args:
            chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
-                of the target`channel (in the format @channelusername).
+                of the target channel (in the format @channelusername).
            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
                the read timeout from the server (instead of the one specified during creation of
                the connection pool).
@@ -2134,7 +2141,7 @@ class Bot(TelegramObject):

        Args:
            chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
-                of the target`channel (in the format @channelusername).
+                of the target channel (in the format @channelusername).
            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
                the read timeout from the server (instead of the one specified during creation of
                the connection pool).
@@ -2166,7 +2173,7 @@ class Bot(TelegramObject):

        Args:
            chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
-                of the target`channel (in the format @channelusername).
+                of the target channel (in the format @channelusername).
            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
                the read timeout from the server (instead of the one specified during creation of
                the connection pool).
@@ -2194,7 +2201,7 @@ class Bot(TelegramObject):

        Args:
            chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
-                of the target`channel (in the format @channelusername).
+                of the target channel (in the format @channelusername).
            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
                the read timeout from the server (instead of the one specified during creation of
                the connection pool).
@@ -2222,7 +2229,7 @@ class Bot(TelegramObject):

        Args:
            chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
-                of the target`channel (in the format @channelusername).
+                of the target channel (in the format @channelusername).
            user_id (:obj:`int`): Unique identifier of the target user.
            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
                the read timeout from the server (instead of the one specified during creation of
@@ -2326,7 +2333,6 @@ class Bot(TelegramObject):
        return WebhookInfo.de_json(result, self)

    @log
-    @message
    def set_game_score(self,
                       user_id,
                       score,
@@ -2385,7 +2391,7 @@ class Bot(TelegramObject):
        if disable_edit_message is not None:
            data['disable_edit_message'] = disable_edit_message

-        return url, data
+        return self._message(url, data, timeout=timeout, **kwargs)

    @log
    def get_game_high_scores(self,
@@ -2436,7 +2442,6 @@ class Bot(TelegramObject):
        return [GameHighScore.de_json(hs, self) for hs in result]

    @log
-    @message
    def send_invoice(self,
                     chat_id,
                     title,
@@ -2560,7 +2565,9 @@ class Bot(TelegramObject):
        if send_email_to_provider is not None:
            data['send_email_to_provider'] = send_email_to_provider

-        return url, data
+        return self._message(url, data, timeout=timeout, disable_notification=disable_notification,
+                             reply_to_message_id=reply_to_message_id, reply_markup=reply_markup,
+                             **kwargs)

    @log
    def answer_shipping_query(self,
@@ -2816,7 +2823,7 @@ class Bot(TelegramObject):

        Args:
            chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
-                of the target`channel (in the format @channelusername).
+                of the target channel (in the format @channelusername).
            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
                the read timeout from the server (instead of the one specified during creation of
                the connection pool).
@@ -2839,7 +2846,7 @@ class Bot(TelegramObject):
        return result

    @log
-    def set_chat_photo(self, chat_id, photo, timeout=None, **kwargs):
+    def set_chat_photo(self, chat_id, photo, timeout=20, **kwargs):
        """Use this method to set a new profile photo for the chat.

        Photos can't be changed for private chats. The bot must be an administrator in the chat
@@ -2847,7 +2854,7 @@ class Bot(TelegramObject):

        Args:
            chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
-                of the target`channel (in the format @channelusername).
+                of the target channel (in the format @channelusername).
            photo (`filelike object`): New chat photo.
            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
                the read timeout from the server (instead of the one specified during creation of
@@ -2886,7 +2893,7 @@ class Bot(TelegramObject):

        Args:
            chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
-                of the target`channel (in the format @channelusername).
+                of the target channel (in the format @channelusername).
            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
                the read timeout from the server (instead of the one specified during creation of
                the connection pool).
@@ -2921,7 +2928,7 @@ class Bot(TelegramObject):

        Args:
            chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
-                of the target`channel (in the format @channelusername).
+                of the target channel (in the format @channelusername).
            title (:obj:`str`): New chat title, 1-255 characters.
            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
                the read timeout from the server (instead of the one specified during creation of
@@ -2956,7 +2963,7 @@ class Bot(TelegramObject):

        Args:
            chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
-                of the target`channel (in the format @channelusername).
+                of the target channel (in the format @channelusername).
            description (:obj:`str`): New chat description, 1-255 characters.
            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
                the read timeout from the server (instead of the one specified during creation of
@@ -2988,7 +2995,7 @@ class Bot(TelegramObject):

        Args:
            chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
-                of the target`channel (in the format @channelusername).
+                of the target channel (in the format @channelusername).
            message_id (:obj:`int`): Identifier of a message to pin.
            disable_notification (:obj:`bool`, optional): Pass True, if it is not necessary to send
                a notification to all group members about the new pinned message.
@@ -3024,7 +3031,7 @@ class Bot(TelegramObject):

        Args:
            chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
-                of the target`channel (in the format @channelusername).
+                of the target channel (in the format @channelusername).
            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
                the read timeout from the server (instead of the one specified during creation of
                the connection pool).
@@ -3075,7 +3082,7 @@ class Bot(TelegramObject):
        return StickerSet.de_json(result, self)

    @log
-    def upload_sticker_file(self, user_id, png_sticker, timeout=None, **kwargs):
+    def upload_sticker_file(self, user_id, png_sticker, timeout=20, **kwargs):
        """
        Use this method to upload a .png file with a sticker for later use in
        :attr:`create_new_sticker_set` and :attr:`add_sticker_to_set` methods (can be used multiple
@@ -3116,7 +3123,7 @@ class Bot(TelegramObject):

    @log
    def create_new_sticker_set(self, user_id, name, title, png_sticker, emojis,
-                               contains_masks=None, mask_position=None, timeout=None, **kwargs):
+                               contains_masks=None, mask_position=None, timeout=20, **kwargs):
        """Use this method to create new sticker set owned by a user.

        The bot will be able to edit the created sticker set.
@@ -3176,7 +3183,7 @@ class Bot(TelegramObject):

    @log
    def add_sticker_to_set(self, user_id, name, png_sticker, emojis, mask_position=None,
-                           timeout=None, **kwargs):
+                           timeout=20, **kwargs):
        """Use this method to add a new sticker to a set created by the bot.

        Note:
@@ -3315,6 +3322,101 @@ class Bot(TelegramObject):

        return result

+    @log
+    def send_poll(self,
+                  chat_id,
+                  question,
+                  options,
+                  disable_notification=None,
+                  reply_to_message_id=None,
+                  reply_markup=None,
+                  timeout=None,
+                  **kwargs):
+        """
+        Use this method to send a native poll. A native poll can't be sent to a private chat.
+
+        Args:
+            chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target private chat.
+            question (:obj:`str`): Poll question, 1-255 characters.
+            options (List[:obj:`str`]): List of answer options, 2-10 strings 1-100 characters each.
+            disable_notification (:obj:`bool`, optional): Sends the message silently. Users will
+                receive a notification with no sound.
+            reply_to_message_id (:obj:`int`, optional): If the message is a reply, ID of the
+                original message.
+            reply_markup (:class:`telegram.ReplyMarkup`, optional): Additional interface options. A
+                JSON-serialized object for an inline keyboard, custom reply keyboard, instructions
+                to remove reply keyboard or to force a reply from the user.
+            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
+                the read timeout from the server (instead of the one specified during creation of
+                the connection pool).
+            **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+
+        Returns:
+            :class:`telegram.Message`: On success, the sent Message is returned.
+
+        Raises:
+            :class:`telegram.TelegramError`
+
+        """
+        url = '{0}/sendPoll'.format(self.base_url)
+
+        data = {
+            'chat_id': chat_id,
+            'question': question,
+            'options': options
+        }
+
+        return self._message(url, data, timeout=timeout, disable_notification=disable_notification,
+                             reply_to_message_id=reply_to_message_id, reply_markup=reply_markup,
+                             **kwargs)
+
+    @log
+    def stop_poll(self,
+                  chat_id,
+                  message_id,
+                  reply_markup=None,
+                  timeout=None,
+                  **kwargs):
+        """
+        Use this method to stop a poll which was sent by the bot.
+
+        Args:
+            chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username
+                of the target channel (in the format @channelusername).
+            message_id (:obj:`int`): Identifier of the original message with the poll.
+            reply_markup (:class:`telegram.ReplyMarkup`, optional): Additional interface options. A
+                JSON-serialized object for an inline keyboard, custom reply keyboard, instructions
+                to remove reply keyboard or to force a reply from the user.
+            timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as
+                the read timeout from the server (instead of the one specified during creation of
+                the connection pool).
+            **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+
+        Returns:
+            :class:`telegram.Poll`: On success, the stopped Poll with the
+                final results is returned.
+
+        Raises:
+            :class:`telegram.TelegramError`
+
+        """
+        url = '{0}/stopPoll'.format(self.base_url)
+
+        data = {
+            'chat_id': chat_id,
+            'message_id': message_id
+        }
+
+        if reply_markup:
+            if isinstance(reply_markup, ReplyMarkup):
+                data['reply_markup'] = reply_markup.to_json()
+            else:
+                data['reply_markup'] = reply_markup
+
+        result = self._request.post(url, data, timeout=timeout)
+
+        return Poll.de_json(result, self)
+
    def to_dict(self):
        data = {'id': self.id, 'username': self.username, 'first_name': self.username}

@@ -3452,3 +3554,7 @@ class Bot(TelegramObject):
    """Alias for :attr:`delete_sticker_from_set`"""
    setPassportDataErrors = set_passport_data_errors
    """Alias for :attr:`set_passport_data_errors`"""
+    sendPoll = send_poll
+    """Alias for :attr:`send_poll`"""
+    stopPoll = stop_poll
+    """Alias for :attr:`stop_poll`"""
@@ -116,16 +116,16 @@ class CallbackQuery(TelegramObject):
        """
        return self.bot.answerCallbackQuery(self.id, *args, **kwargs)

-    def edit_message_text(self, *args, **kwargs):
+    def edit_message_text(self, text, *args, **kwargs):
        """Shortcut for either::

-            bot.edit_message_text(chat_id=update.callback_query.message.chat_id,
+            bot.edit_message_text(text, chat_id=update.callback_query.message.chat_id,
                                message_id=update.callback_query.message.message_id,
                                *args, **kwargs)

        or::

-            bot.edit_message_text(inline_message_id=update.callback_query.inline_message_id,
+            bot.edit_message_text(text, inline_message_id=update.callback_query.inline_message_id,
                                *args, **kwargs)

        Returns:
@@ -134,22 +134,24 @@ class CallbackQuery(TelegramObject):

        """
        if self.inline_message_id:
-            return self.bot.edit_message_text(
-                inline_message_id=self.inline_message_id, *args, **kwargs)
+            return self.bot.edit_message_text(text, inline_message_id=self.inline_message_id,
+                                              *args, **kwargs)
        else:
-            return self.bot.edit_message_text(
-                chat_id=self.message.chat_id, message_id=self.message.message_id, *args, **kwargs)
+            return self.bot.edit_message_text(text, chat_id=self.message.chat_id,
+                                              message_id=self.message.message_id, *args, **kwargs)

-    def edit_message_caption(self, *args, **kwargs):
+    def edit_message_caption(self, caption, *args, **kwargs):
        """Shortcut for either::

-            bot.edit_message_caption(chat_id=update.callback_query.message.chat_id,
+            bot.edit_message_caption(caption=caption,
+                                   chat_id=update.callback_query.message.chat_id,
                                   message_id=update.callback_query.message.message_id,
                                   *args, **kwargs)

        or::

-            bot.edit_message_caption(inline_message_id=update.callback_query.inline_message_id,
+            bot.edit_message_caption(caption=caption
+                                    inline_message_id=update.callback_query.inline_message_id,
                                   *args, **kwargs)

        Returns:
@@ -158,22 +160,26 @@ class CallbackQuery(TelegramObject):

        """
        if self.inline_message_id:
-            return self.bot.edit_message_caption(
-                inline_message_id=self.inline_message_id, *args, **kwargs)
+            return self.bot.edit_message_caption(caption=caption,
+                                                 inline_message_id=self.inline_message_id,
+                                                 *args, **kwargs)
        else:
-            return self.bot.edit_message_caption(
-                chat_id=self.message.chat_id, message_id=self.message.message_id, *args, **kwargs)
+            return self.bot.edit_message_caption(caption=caption, chat_id=self.message.chat_id,
+                                                 message_id=self.message.message_id,
+                                                 *args, **kwargs)

-    def edit_message_reply_markup(self, *args, **kwargs):
+    def edit_message_reply_markup(self, reply_markup, *args, **kwargs):
        """Shortcut for either::

            bot.edit_message_replyMarkup(chat_id=update.callback_query.message.chat_id,
                                       message_id=update.callback_query.message.message_id,
+                                       reply_markup=reply_markup,
                                       *args, **kwargs)

        or::

            bot.edit_message_reply_markup(inline_message_id=update.callback_query.inline_message_id,
+                                        reply_markup=reply_markup,
                                       *args, **kwargs)

        Returns:
@@ -182,8 +188,11 @@ class CallbackQuery(TelegramObject):

        """
        if self.inline_message_id:
-            return self.bot.edit_message_reply_markup(
-                inline_message_id=self.inline_message_id, *args, **kwargs)
+            return self.bot.edit_message_reply_markup(reply_markup=reply_markup,
+                                                      inline_message_id=self.inline_message_id,
+                                                      *args, **kwargs)
        else:
-            return self.bot.edit_message_reply_markup(
-                chat_id=self.message.chat_id, message_id=self.message.message_id, *args, **kwargs)
+            return self.bot.edit_message_reply_markup(reply_markup=reply_markup,
+                                                      chat_id=self.message.chat_id,
+                                                      message_id=self.message.message_id,
+                                                      *args, **kwargs)
@@ -337,3 +337,16 @@ class Chat(TelegramObject):

        """
        return self.bot.send_voice(self.id, *args, **kwargs)
+
+    def send_poll(self, *args, **kwargs):
+        """Shortcut for::
+
+            bot.send_poll(Chat.id, *args, **kwargs)
+
+        Where Chat is the current instance.
+
+        Returns:
+            :class:`telegram.Message`: On success, instance representing the message posted.
+
+        """
+        return self.bot.send_poll(self.id, *args, **kwargs)
@@ -46,6 +46,8 @@ class ChatMember(TelegramObject):
        can_pin_messages (:obj:`bool`): Optional. If the administrator can pin messages.
        can_promote_members (:obj:`bool`): Optional. If the administrator can add new
            administrators.
+        is_member (:obj:`bool`): Optional. Restricted only. True, if the user is a member of the
+            chat at the moment of the request.
        can_send_messages (:obj:`bool`): Optional. If the user can send text messages, contacts,
            locations and venues.
        can_send_media_messages (:obj:`bool`): Optional. If the user can send media messages,
@@ -81,6 +83,8 @@ class ChatMember(TelegramObject):
            administrator can add new administrators with a subset of his own privileges or demote
            administrators that he has promoted, directly or indirectly (promoted by administrators
            that were appointed by the user).
+        is_member (:obj:`bool`, optional): Restricted only. True, if the user is a member of the
+            chat at the moment of the request.
        can_send_messages (:obj:`bool`, optional): Restricted only. True, if the user can send text
            messages, contacts, locations and venues.
        can_send_media_messages (:obj:`bool`, optional): Restricted only. True, if the user can
@@ -111,7 +115,7 @@ class ChatMember(TelegramObject):
                 can_restrict_members=None, can_pin_messages=None,
                 can_promote_members=None, can_send_messages=None,
                 can_send_media_messages=None, can_send_other_messages=None,
-                 can_add_web_page_previews=None, **kwargs):
+                 can_add_web_page_previews=None, is_member=None, **kwargs):
        # Required
        self.user = user
        self.status = status
@@ -129,6 +133,7 @@ class ChatMember(TelegramObject):
        self.can_send_media_messages = can_send_media_messages
        self.can_send_other_messages = can_send_other_messages
        self.can_add_web_page_previews = can_add_web_page_previews
+        self.is_member = is_member

        self._id_attrs = (self.user, self.status)

@@ -21,7 +21,7 @@ The following constants were extracted from the

 Attributes:
    MAX_MESSAGE_LENGTH (:obj:`int`): 4096
-    MAX_CAPTION_LENGTH (:obj:`int`): 200
+    MAX_CAPTION_LENGTH (:obj:`int`): 1024
    SUPPORTED_WEBHOOK_PORTS (List[:obj:`int`]): [443, 80, 88, 8443]
    MAX_FILESIZE_DOWNLOAD (:obj:`int`): In bytes (20MB)
    MAX_FILESIZE_UPLOAD (:obj:`int`): In bytes (50MB)
@@ -40,7 +40,7 @@ Attributes:
 """

 MAX_MESSAGE_LENGTH = 4096
-MAX_CAPTION_LENGTH = 200
+MAX_CAPTION_LENGTH = 1024

 # constants above this line are tested

@@ -57,7 +57,6 @@ class Unauthorized(TelegramError):


 class InvalidToken(TelegramError):
-
    def __init__(self):
        super(InvalidToken, self).__init__('Invalid token')

@@ -71,7 +70,6 @@ class BadRequest(NetworkError):


 class TimedOut(NetworkError):
-
    def __init__(self):
        super(TimedOut, self).__init__('Timed out')

@@ -100,3 +98,16 @@ class RetryAfter(TelegramError):
        super(RetryAfter,
              self).__init__('Flood control exceeded. Retry in {} seconds'.format(retry_after))
        self.retry_after = float(retry_after)
+
+
+class Conflict(TelegramError):
+    """
+        Raised when a long poll or webhook conflicts with another one.
+
+        Args:
+            msg (:obj:`str`): The message from telegrams server.
+
+    """
+
+    def __init__(self, msg):
+        super(Conflict, self).__init__(msg)
@@ -18,16 +18,20 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """Extensions over the Telegram Bot API to facilitate bot making"""

+from .basepersistence import BasePersistence
+from .picklepersistence import PicklePersistence
+from .dictpersistence import DictPersistence
+from .handler import Handler
+from .callbackcontext import CallbackContext
 from .dispatcher import Dispatcher, DispatcherHandlerStop, run_async
 from .jobqueue import JobQueue, Job
 from .updater import Updater
 from .callbackqueryhandler import CallbackQueryHandler
 from .choseninlineresulthandler import ChosenInlineResultHandler
-from .commandhandler import CommandHandler
-from .handler import Handler
 from .inlinequeryhandler import InlineQueryHandler
-from .messagehandler import MessageHandler
 from .filters import BaseFilter, Filters
+from .messagehandler import MessageHandler
+from .commandhandler import CommandHandler, PrefixHandler
 from .regexhandler import RegexHandler
 from .stringcommandhandler import StringCommandHandler
 from .stringregexhandler import StringRegexHandler
@@ -43,4 +47,5 @@ __all__ = ('Dispatcher', 'JobQueue', 'Job', 'Updater', 'CallbackQueryHandler',
           'MessageHandler', 'BaseFilter', 'Filters', 'RegexHandler', 'StringCommandHandler',
           'StringRegexHandler', 'TypeHandler', 'ConversationHandler',
           'PreCheckoutQueryHandler', 'ShippingQueryHandler', 'MessageQueue', 'DelayQueue',
-           'DispatcherHandlerStop', 'run_async')
+           'DispatcherHandlerStop', 'run_async', 'CallbackContext', 'BasePersistence',
+           'PicklePersistence', 'DictPersistence', 'PrefixHandler')
@@ -0,0 +1,123 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2018
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the BasePersistence class."""
+
+
+class BasePersistence(object):
+    """Interface class for adding persistence to your bot.
+    Subclass this object for different implementations of a persistent bot.
+
+    All relevant methods must be overwritten. This means:
+
+    * If :attr:`store_chat_data` is ``True`` you must overwrite :meth:`get_chat_data` and
+      :meth:`update_chat_data`.
+    * If :attr:`store_user_data` is ``True`` you must overwrite :meth:`get_user_data` and
+      :meth:`update_user_data`.
+    * If you want to store conversation data with :class:`telegram.ext.ConversationHandler`, you
+      must overwrite :meth:`get_conversations` and :meth:`update_conversation`.
+    * :meth:`flush` will be called when the bot is shutdown.
+
+    Attributes:
+        store_user_data (:obj:`bool`): Optional, Whether user_data should be saved by this
+            persistence class.
+        store_chat_data (:obj:`bool`): Optional. Whether chat_data should be saved by this
+            persistence class.
+
+    Args:
+        store_user_data (:obj:`bool`, optional): Whether user_data should be saved by this
+            persistence class. Default is ``True``.
+        store_chat_data (:obj:`bool`, optional): Whether chat_data should be saved by this
+            persistence class. Default is ``True`` .
+    """
+
+    def __init__(self, store_user_data=True, store_chat_data=True):
+        self.store_user_data = store_user_data
+        self.store_chat_data = store_chat_data
+
+    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
+        ``defaultdict(dict)``.
+
+        Returns:
+            :obj:`defaultdict`: The restored user data.
+        """
+        raise NotImplementedError
+
+    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
+        ``defaultdict(dict)``.
+
+        Returns:
+            :obj:`defaultdict`: The restored chat data.
+        """
+        raise NotImplementedError
+
+    def get_conversations(self, name):
+        """"Will be called by :class:`telegram.ext.Dispatcher` when a
+        :class:`telegram.ext.ConversationHandler` is added if
+        :attr:`telegram.ext.ConversationHandler.persistent` is ``True``.
+        It should return the conversations for the handler with `name` or an empty ``dict``
+
+        Args:
+            name (:obj:`str`): The handlers name.
+
+        Returns:
+            :obj:`dict`: The restored conversations for the handler.
+        """
+        raise NotImplementedError
+
+    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.
+
+        Args:
+            name (:obj:`str`): The handlers name.
+            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
+
+    def update_user_data(self, user_id, data):
+        """Will be called by the :class:`telegram.ext.Dispatcher` after a handler has
+        handled an update.
+
+        Args:
+            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
+
+    def update_chat_data(self, chat_id, data):
+        """Will be called by the :class:`telegram.ext.Dispatcher` after a handler has
+        handled an update.
+
+        Args:
+            chat_id (:obj:`int`): The chat the data might have been changed for.
+            data (:obj:`dict`): The :attr:`telegram.ext.dispatcher.chat_data` [user_id].
+        """
+        raise NotImplementedError
+
+    def flush(self):
+        """Will be called by :class:`telegram.ext.Updater` upon receiving a stop signal. Gives the
+        persistence a chance to finish up saving or close a database connection gracefully. If this
+        is not of any importance just pass will be sufficient.
+        """
+        pass
@@ -0,0 +1,146 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2018
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the CallbackContext class."""
+
+from telegram import Update
+
+
+class CallbackContext(object):
+    """
+    This is a context object passed to the callback called by :class:`telegram.ext.Handler`
+    or by the :class:`telegram.ext.Dispatcher` in an error handler added by
+    :attr:`telegram.ext.Dispatcher.add_error_handler` or to the callback of a
+    :class:`telegram.ext.Job`.
+
+    Note:
+        :class:`telegram.ext.Dispatcher` will create a single context for an entire update. This
+        means that if you got 2 handlers in different groups and they both get called, they will
+        get passed the same `CallbackContext` object (of course with proper attributes like
+        `.matches` differing). This allows you to add custom attributes in a lower handler group
+        callback, and then subsequently access those attributes in a higher handler group callback.
+        Note that the attributes on `CallbackContext` might change in the future, so make sure to
+        use a fairly unique name for the attributes.
+
+    Warning:
+         Do not combine custom attributes and @run_async. Due to how @run_async works, it will
+         almost certainly execute the callbacks for an update out of order, and the attributes
+         that you think you added will not be present.
+
+    Attributes:
+        chat_data (:obj:`dict`, optional): A dict that can be used to keep any data in. For each
+            update from the same chat it will be the same ``dict``.
+        user_data (:obj:`dict`, optional): A dict that can be used to keep any data in. For each
+            update from the same user it will be the same ``dict``.
+        matches (List[:obj:`re match object`], optional): If the associated update originated from
+            a regex-supported handler or had a :class:`Filters.regex`, this will contain a list of
+            match objects for every pattern where ``re.search(pattern, string)`` returned a match.
+            Note that filters short circuit, so combined regex filters will not always
+            be evaluated.
+        args (List[:obj:`str`], optional): Arguments passed to a command if the associated update
+            is handled by :class:`telegram.ext.CommandHandler`, :class:`telegram.ext.PrefixHandler`
+            or :class:`telegram.ext.StringCommandHandler`. It contains a list of the words in the
+            text after the command, using any whitespace string as a delimiter.
+        error (:class:`telegram.TelegramError`, optional): The Telegram error that was raised.
+            Only present when passed to a error handler registered with
+            :attr:`telegram.ext.Dispatcher.add_error_handler`.
+        job (:class:`telegram.ext.Job`): The job that that originated this callback.
+            Only present when passed to the callback of :class:`telegram.ext.Job`.
+
+    """
+
+    def __init__(self, dispatcher):
+        """
+        Args:
+            dispatcher (:class:`telegram.ext.Dispatcher`):
+        """
+        if not dispatcher.use_context:
+            raise ValueError('CallbackContext should not be used with a non context aware '
+                             'dispatcher!')
+        self._dispatcher = dispatcher
+        self.chat_data = None
+        self.user_data = None
+        self.args = None
+        self.matches = None
+        self.error = None
+        self.job = None
+
+    @classmethod
+    def from_error(cls, update, error, dispatcher):
+        self = cls.from_update(update, dispatcher)
+        self.error = error
+        return self
+
+    @classmethod
+    def from_update(cls, update, dispatcher):
+        self = cls(dispatcher)
+        if update is not None and isinstance(update, Update):
+            chat = update.effective_chat
+            user = update.effective_user
+
+            if chat:
+                self.chat_data = dispatcher.chat_data[chat.id]
+            if user:
+                self.user_data = dispatcher.user_data[user.id]
+        return self
+
+    @classmethod
+    def from_job(cls, job, dispatcher):
+        self = cls(dispatcher)
+        self.job = job
+        return self
+
+    def update(self, data):
+        self.__dict__.update(data)
+
+    @property
+    def bot(self):
+        """:class:`telegram.Bot`: The bot associated with this context."""
+        return self._dispatcher.bot
+
+    @property
+    def job_queue(self):
+        """
+        :class:`telegram.ext.JobQueue`: The ``JobQueue`` used by the
+            :class:`telegram.ext.Dispatcher` and (usually) the :class:`telegram.ext.Updater`
+            associated with this context.
+
+        """
+        return self._dispatcher.job_queue
+
+    @property
+    def update_queue(self):
+        """
+        :class:`queue.Queue`: The ``Queue`` instance used by the
+            :class:`telegram.ext.Dispatcher` and (usually) the :class:`telegram.ext.Updater`
+            associated with this context.
+
+        """
+        return self._dispatcher.update_queue
+
+    @property
+    def match(self):
+        """
+        `Regex match type`: The first match from :attr:`matches`.
+            Useful if you are only filtering using a single regex filter.
+            Returns `None` if :attr:`matches` is empty.
+        """
+        try:
+            return self.matches[0]  # pylint: disable=unsubscriptable-object
+        except (IndexError, TypeError):
+            return None
@@ -33,19 +33,19 @@ class CallbackQueryHandler(Handler):

    Attributes:
        callback (:obj:`callable`): The callback function for this handler.
-        pass_update_queue (:obj:`bool`): Optional. Determines whether ``update_queue`` will be
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Optional. Determines whether ``job_queue`` will be passed to
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
            the callback function.
        pattern (:obj:`str` | `Pattern`): Optional. Regex pattern to test
            :attr:`telegram.CallbackQuery.data` against.
-        pass_groups (:obj:`bool`): Optional. Determines whether ``groups`` will be passed to the
+        pass_groups (:obj:`bool`): Determines whether ``groups`` will be passed to the
            callback function.
-        pass_groupdict (:obj:`bool`): Optional. Determines whether ``groupdict``. will be passed to
+        pass_groupdict (:obj:`bool`): Determines whether ``groupdict``. will be passed to
            the callback function.
-        pass_user_data (:obj:`bool`): Optional. Determines whether ``user_data`` will be passed to
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
            the callback function.
-        pass_chat_data (:obj:`bool`): Optional. Determines whether ``chat_data`` will be passed to
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
            the callback function.

    Note:
@@ -54,31 +54,45 @@ class CallbackQueryHandler(Handler):
        either the user or the chat that the update was sent in. For each update from the same user
        or in the same chat, it will be the same ``dict``.

+        Note that this is DEPRECATED, and you should use context based callbacks. See
+        https://git.io/fxJuV for more info.
+
    Args:
-        callback (:obj:`callable`): A function that takes ``bot, update`` as positional arguments.
-            It will be called when the :attr:`check_update` has determined that an update should be
-            processed by this handler.
+        callback (:obj:`callable`): The callback function for this handler. Will be called when
+            :attr:`check_update` has determined that an update should be processed by this handler.
+            Callback signature for context based API:
+
+                ``def callback(update: Update, context: CallbackContext)``
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
        pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
            instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
            that contains new updates which can be used to insert updates. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``job_queue`` will be passed to the callback function. It will be a
            :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
            which can be used to schedule new jobs. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pattern (:obj:`str` | `Pattern`, optional): Regex pattern. If not ``None``, ``re.match``
            is used on :attr:`telegram.CallbackQuery.data` to determine if an update should be
            handled by this handler.
        pass_groups (:obj:`bool`, optional): If the callback should be passed the result of
            ``re.match(pattern, data).groups()`` as a keyword argument called ``groups``.
            Default is ``False``
+            DEPRECATED: Please switch to context based callbacks.
        pass_groupdict (:obj:`bool`, optional): If the callback should be passed the result of
            ``re.match(pattern, data).groupdict()`` as a keyword argument called ``groupdict``.
            Default is ``False``
+            DEPRECATED: Please switch to context based callbacks.
        pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``user_data`` will be passed to the callback function. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``chat_data`` will be passed to the callback function. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.

    """

@@ -119,25 +133,22 @@ class CallbackQueryHandler(Handler):
            if self.pattern:
                if update.callback_query.data:
                    match = re.match(self.pattern, update.callback_query.data)
-                    return bool(match)
+                    if match:
+                        return match
            else:
                return True

-    def handle_update(self, update, dispatcher):
-        """Send the update to the :attr:`callback`.
-
-        Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
-            dispatcher (:class:`telegram.ext.Dispatcher`): Dispatcher that originated the Update.
-
-        """
-        optional_args = self.collect_optional_args(dispatcher, update)
+    def collect_optional_args(self, dispatcher, update=None, check_result=None):
+        optional_args = super(CallbackQueryHandler, self).collect_optional_args(dispatcher,
+                                                                                update,
+                                                                                check_result)
        if self.pattern:
-            match = re.match(self.pattern, update.callback_query.data)
-
            if self.pass_groups:
-                optional_args['groups'] = match.groups()
+                optional_args['groups'] = check_result.groups()
            if self.pass_groupdict:
-                optional_args['groupdict'] = match.groupdict()
+                optional_args['groupdict'] = check_result.groupdict()
+        return optional_args

-        return self.callback(dispatcher.bot, update, **optional_args)
+    def collect_additional_context(self, context, update, dispatcher, check_result):
+        if self.pattern:
+            context.matches = [check_result]
@@ -18,9 +18,8 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the ChosenInlineResultHandler class."""

-from .handler import Handler
 from telegram import Update
-from telegram.utils.deprecate import deprecate
+from .handler import Handler


 class ChosenInlineResultHandler(Handler):
@@ -28,13 +27,13 @@ class ChosenInlineResultHandler(Handler):

    Attributes:
        callback (:obj:`callable`): The callback function for this handler.
-        pass_update_queue (:obj:`bool`): Optional. Determines whether ``update_queue`` will be
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Optional. Determines whether ``job_queue`` will be passed to
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
            the callback function.
-        pass_user_data (:obj:`bool`): Optional. Determines whether ``user_data`` will be passed to
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
            the callback function.
-        pass_chat_data (:obj:`bool`): Optional. Determines whether ``chat_data`` will be passed to
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
            the callback function.

    Note:
@@ -43,38 +42,37 @@ class ChosenInlineResultHandler(Handler):
        either the user or the chat that the update was sent in. For each update from the same user
        or in the same chat, it will be the same ``dict``.

+        Note that this is DEPRECATED, and you should use context based callbacks. See
+        https://git.io/fxJuV for more info.
+
    Args:
-        callback (:obj:`callable`): A function that takes ``bot, update`` as positional arguments.
-            It will be called when the :attr:`check_update` has determined that an update should be
-            processed by this handler.
+        callback (:obj:`callable`): The callback function for this handler. Will be called when
+            :attr:`check_update` has determined that an update should be processed by this handler.
+            Callback signature for context based API:
+
+            ``def callback(update: Update, context: CallbackContext)``
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
        pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
            instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
            that contains new updates which can be used to insert updates. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``job_queue`` will be passed to the callback function. It will be a
            :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
            which can be used to schedule new jobs. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``user_data`` will be passed to the callback function. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``chat_data`` will be passed to the callback function. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.

    """

-    def __init__(self,
-                 callback,
-                 pass_update_queue=False,
-                 pass_job_queue=False,
-                 pass_user_data=False,
-                 pass_chat_data=False):
-        super(ChosenInlineResultHandler, self).__init__(
-            callback,
-            pass_update_queue=pass_update_queue,
-            pass_job_queue=pass_job_queue,
-            pass_user_data=pass_user_data,
-            pass_chat_data=pass_chat_data)
-
    def check_update(self, update):
        """Determines whether an update should be passed to this handlers :attr:`callback`.

@@ -86,20 +84,3 @@ class ChosenInlineResultHandler(Handler):

        """
        return isinstance(update, Update) and update.chosen_inline_result
-
-    def handle_update(self, update, dispatcher):
-        """Send the update to the :attr:`callback`.
-
-        Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
-            dispatcher (:class:`telegram.ext.Dispatcher`): Dispatcher that originated the Update.
-
-        """
-        optional_args = self.collect_optional_args(dispatcher, update)
-
-        return self.callback(dispatcher.bot, update, **optional_args)
-
-    # old non-PEP8 Handler methods
-    m = "telegram.ChosenInlineResultHandler."
-    checkUpdate = deprecate(check_update, m + "checkUpdate", m + "check_update")
-    handleUpdate = deprecate(handle_update, m + "handleUpdate", m + "handle_update")
@@ -16,38 +16,48 @@
 #
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
-"""This module contains the CommandHandler class."""
+"""This module contains the CommandHandler and PrefixHandler classes."""
+import re
 import warnings

 from future.utils import string_types

+from telegram.ext import Filters
+from telegram.utils.deprecate import TelegramDeprecationWarning
+
+from telegram import Update, MessageEntity
 from .handler import Handler
-from telegram import Update


 class CommandHandler(Handler):
    """Handler class to handle Telegram commands.

    Commands are Telegram messages that start with ``/``, optionally followed by an ``@`` and the
-    bot's name and/or some additional text.
+    bot's name and/or some additional text. The handler will add a ``list`` to the
+    :class:`CallbackContext` named :attr:`CallbackContext.args`. It will contain a list of strings,
+    which is the text following the command split on single or consecutive whitespace characters.
+
+    By default the handler listens to messages as well as edited messages. To change this behavior
+    use ``~Filters.update.edited_message`` in the filter argument.

    Attributes:
        command (:obj:`str` | List[:obj:`str`]): The command or list of commands this handler
-            should listen for.
+            should listen for. Limitations are the same as described here
+            https://core.telegram.org/bots#commands
        callback (:obj:`callable`): The callback function for this handler.
        filters (:class:`telegram.ext.BaseFilter`): Optional. Only allow updates with these
            Filters.
-        allow_edited (:obj:`bool`): Optional. Determines Whether the handler should also accept
+        allow_edited (:obj:`bool`): Determines Whether the handler should also accept
            edited messages.
-        pass_args (:obj:`bool`): Optional. Determines whether the handler should be passed
+        pass_args (:obj:`bool`): Determines whether the handler should be passed
            ``args``.
-        pass_update_queue (:obj:`bool`): Optional. Determines whether ``update_queue`` will be
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Optional. Determines whether ``job_queue`` will be passed to
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
            the callback function.
-        pass_user_data (:obj:`bool`): Optional. Determines whether ``user_data`` will be passed to
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
            the callback function.
-        pass_chat_data (:obj:`bool`): Optional. Determines whether ``chat_data`` will be passed to
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
            the callback function.

    Note:
@@ -56,42 +66,60 @@ class CommandHandler(Handler):
        either the user or the chat that the update was sent in. For each update from the same user
        or in the same chat, it will be the same ``dict``.

+        Note that this is DEPRECATED, and you should use context based callbacks. See
+        https://git.io/fxJuV for more info.
+
    Args:
        command (:obj:`str` | List[:obj:`str`]): The command or list of commands this handler
-            should listen for.
-        callback (:obj:`callable`): A function that takes ``bot, update`` as positional arguments.
-            It will be called when the :attr:`check_update` has determined that an update should be
-            processed by this handler.
+            should listen for. Limitations are the same as described here
+            https://core.telegram.org/bots#commands
+        callback (:obj:`callable`): The callback function for this handler. Will be called when
+            :attr:`check_update` has determined that an update should be processed by this handler.
+            Callback signature for context based API:
+
+            ``def callback(update: Update, context: CallbackContext)``
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
        filters (:class:`telegram.ext.BaseFilter`, optional): A filter inheriting from
            :class:`telegram.ext.filters.BaseFilter`. Standard filters can be found in
            :class:`telegram.ext.filters.Filters`. Filters can be combined using bitwise
            operators (& for and, | for or, ~ for not).
        allow_edited (:obj:`bool`, optional): Determines whether the handler should also accept
            edited messages. Default is ``False``.
+            DEPRECATED: Edited is allowed by default. To change this behavior use
+            ``~Filters.update.edited_message``.
        pass_args (:obj:`bool`, optional): Determines whether the handler should be passed the
            arguments passed to the command as a keyword argument called ``args``. It will contain
            a list of strings, which is the text following the command split on single or
            consecutive whitespace characters. Default is ``False``
+            DEPRECATED: Please switch to context based callbacks.
        pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
            instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
            that contains new updates which can be used to insert updates. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``job_queue`` will be passed to the callback function. It will be a
            :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
            which can be used to schedule new jobs. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``user_data`` will be passed to the callback function. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``chat_data`` will be passed to the callback function. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.

+    Raises:
+        ValueError - when command is too long or has illegal chars.
    """

    def __init__(self,
                 command,
                 callback,
                 filters=None,
-                 allow_edited=False,
+                 allow_edited=None,
                 pass_args=False,
                 pass_update_queue=False,
                 pass_job_queue=False,
@@ -108,16 +136,22 @@ class CommandHandler(Handler):
            self.command = [command.lower()]
        else:
            self.command = [x.lower() for x in command]
-        self.filters = filters
-        self.allow_edited = allow_edited
-        self.pass_args = pass_args
+        for comm in self.command:
+            if not re.match(r'^[\da-z_]{1,32}$', comm):
+                raise ValueError('Command is not a valid bot command')

-        # We put this up here instead of with the rest of checking code
-        # in check_update since we don't wanna spam a ton
-        if isinstance(self.filters, list):
-            warnings.warn('Using a list of filters in MessageHandler is getting '
-                          'deprecated, please use bitwise operators (& and |) '
-                          'instead. More info: https://git.io/vPTbc.')
+        if filters:
+            self.filters = Filters.update.messages & filters
+        else:
+            self.filters = Filters.update.messages
+
+        if allow_edited is not None:
+            warnings.warn('allow_edited is deprecated. See https://git.io/fxJuV for more info',
+                          TelegramDeprecationWarning,
+                          stacklevel=2)
+            if not allow_edited:
+                self.filters &= ~Filters.update.edited_message
+        self.pass_args = pass_args

    def check_update(self, update):
        """Determines whether an update should be passed to this handlers :attr:`callback`.
@@ -126,48 +160,189 @@ class CommandHandler(Handler):
            update (:class:`telegram.Update`): Incoming telegram update.

        Returns:
-            :obj:`bool`
+            :obj:`list`: The list of args for the handler

        """
-        if (isinstance(update, Update)
-                and (update.message or update.edited_message and self.allow_edited)):
-            message = update.message or update.edited_message
+        if isinstance(update, Update) and update.effective_message:
+            message = update.effective_message

-            if message.text and message.text.startswith('/') and len(message.text) > 1:
-                first_word = message.text_html.split(None, 1)[0]
-                if len(first_word) > 1 and first_word.startswith('/'):
-                    command = first_word[1:].split('@')
-                    command.append(
-                        message.bot.username)  # in case the command was sent without a username
+            if (message.entities and message.entities[0].type == MessageEntity.BOT_COMMAND
+                    and message.entities[0].offset == 0):
+                command = message.text[1:message.entities[0].length]
+                args = message.text.split()[1:]
+                command = command.split('@')
+                command.append(message.bot.username)

-                    if not (command[0].lower() in self.command
-                            and command[1].lower() == message.bot.username.lower()):
-                        return False
+                if not (command[0].lower() in self.command
+                        and command[1].lower() == message.bot.username.lower()):
+                    return None

-                    if self.filters is None:
-                        res = True
-                    elif isinstance(self.filters, list):
-                        res = any(func(message) for func in self.filters)
-                    else:
-                        res = self.filters(message)
+                filter_result = self.filters(update)
+                if filter_result:
+                    return args, filter_result
+                else:
+                    return False

-                    return res
+    def collect_optional_args(self, dispatcher, update=None, check_result=None):
+        optional_args = super(CommandHandler, self).collect_optional_args(dispatcher, update)
+        if self.pass_args:
+            optional_args['args'] = check_result[0]
+        return optional_args

-        return False
+    def collect_additional_context(self, context, update, dispatcher, check_result):
+        context.args = check_result[0]
+        if isinstance(check_result[1], dict):
+            context.update(check_result[1])

-    def handle_update(self, update, dispatcher):
-        """Send the update to the :attr:`callback`.
+
+class PrefixHandler(CommandHandler):
+    """Handler class to handle custom prefix commands
+
+    This is a intermediate handler between :class:`MessageHandler` and :class:`CommandHandler`.
+    It supports configurable commands with the same options as CommandHandler. It will respond to
+    every combination of :attr:`prefix` and :attr:`command`. It will add a ``list`` to the
+    :class:`CallbackContext` named :attr:`CallbackContext.args`. It will contain a list of strings,
+    which is the text following the command split on single or consecutive whitespace characters.
+
+    Examples::
+
+        Single prefix and command:
+
+            PrefixHandler('!', 'test', callback) will respond to '!test'.
+
+        Multiple prefixes, single command:
+
+            PrefixHandler(['!', '#'], 'test', callback) will respond to '!test' and
+            '#test'.
+
+        Miltiple prefixes and commands:
+
+            PrefixHandler(['!', '#'], ['test', 'help`], callback) will respond to '!test',
+            '#test', '!help' and '#help'.
+
+
+    By default the handler listens to messages as well as edited messages. To change this behavior
+    use ~``Filters.update.edited_message``.
+
+    Attributes:
+        prefix (:obj:`str` | List[:obj:`str`]): The prefix(es) that will precede :attr:`command`.
+        command (:obj:`str` | List[:obj:`str`]): The command or list of commands this handler
+            should listen for.
+        callback (:obj:`callable`): The callback function for this handler.
+        filters (:class:`telegram.ext.BaseFilter`): Optional. Only allow updates with these
+            Filters.
+        pass_args (:obj:`bool`): Determines whether the handler should be passed
+            ``args``.
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
+            passed to the callback function.
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
+            the callback function.
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
+            the callback function.
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
+            the callback function.
+
+    Note:
+        :attr:`pass_user_data` and :attr:`pass_chat_data` determine whether a ``dict`` you
+        can use to keep any data in will be sent to the :attr:`callback` function. Related to
+        either the user or the chat that the update was sent in. For each update from the same user
+        or in the same chat, it will be the same ``dict``.
+
+        Note that this is DEPRECATED, and you should use context based callbacks. See
+        https://git.io/fxJuV for more info.
+
+    Args:
+        prefix (:obj:`str` | List[:obj:`str`]): The prefix(es) that will precede :attr:`command`.
+        command (:obj:`str` | List[:obj:`str`]): The command or list of commands this handler
+            should listen for.
+        callback (:obj:`callable`): The callback function for this handler. Will be called when
+            :attr:`check_update` has determined that an update should be processed by this handler.
+            Callback signature for context based API:
+
+            ``def callback(update: Update, context: CallbackContext)``
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
+        filters (:class:`telegram.ext.BaseFilter`, optional): A filter inheriting from
+            :class:`telegram.ext.filters.BaseFilter`. Standard filters can be found in
+            :class:`telegram.ext.filters.Filters`. Filters can be combined using bitwise
+            operators (& for and, | for or, ~ for not).
+        pass_args (:obj:`bool`, optional): Determines whether the handler should be passed the
+            arguments passed to the command as a keyword argument called ``args``. It will contain
+            a list of strings, which is the text following the command split on single or
+            consecutive whitespace characters. Default is ``False``
+            DEPRECATED: Please switch to context based callbacks.
+        pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
+            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
+            instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
+            that contains new updates which can be used to insert updates. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
+        pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
+            ``job_queue`` will be passed to the callback function. It will be a
+            :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
+            which can be used to schedule new jobs. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
+        pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
+            ``user_data`` will be passed to the callback function. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
+        pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
+            ``chat_data`` will be passed to the callback function. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
+
+    """
+
+    def __init__(self,
+                 prefix,
+                 command,
+                 callback,
+                 filters=None,
+                 pass_args=False,
+                 pass_update_queue=False,
+                 pass_job_queue=False,
+                 pass_user_data=False,
+                 pass_chat_data=False):
+
+        super(PrefixHandler, self).__init__(
+            'nocommand', callback, filters=filters, allow_edited=None, pass_args=pass_args,
+            pass_update_queue=pass_update_queue,
+            pass_job_queue=pass_job_queue,
+            pass_user_data=pass_user_data,
+            pass_chat_data=pass_chat_data)
+
+        if isinstance(prefix, string_types):
+            self.prefix = [prefix.lower()]
+        else:
+            self.prefix = prefix
+        if isinstance(command, string_types):
+            self.command = [command.lower()]
+        else:
+            self.command = command
+        self.command = [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`.

        Args:
            update (:class:`telegram.Update`): Incoming telegram update.
-            dispatcher (:class:`telegram.ext.Dispatcher`): Dispatcher that originated the Update.
+
+        Returns:
+            :obj:`list`: The list of args for the handler

        """
-        optional_args = self.collect_optional_args(dispatcher, update)
+        if isinstance(update, Update) and update.effective_message:
+            message = update.effective_message

-        message = update.message or update.edited_message
+            if message.text:
+                text_list = message.text.split()
+                if text_list[0].lower() not in self.command:
+                    return None
+                filter_result = self.filters(update)
+                if filter_result:
+                    return text_list[1:], filter_result
+                else:
+                    return False

-        if self.pass_args:
-            optional_args['args'] = message.text.split()[1:]
-
-        return self.callback(dispatcher.bot, update, **optional_args)
+    def collect_additional_context(self, context, update, dispatcher, check_result):
+        context.args = check_result[0]
+        if isinstance(check_result[1], dict):
+            context.update(check_result[1])
@@ -19,13 +19,21 @@
 """This module contains the ConversationHandler."""

 import logging
+import warnings

 from telegram import Update
 from telegram.ext import (Handler, CallbackQueryHandler, InlineQueryHandler,
-                          ChosenInlineResultHandler)
+                          ChosenInlineResultHandler, CallbackContext)
 from telegram.utils.promise import Promise


+class _ConversationTimeoutContext(object):
+    def __init__(self, conversation_key, update, dispatcher):
+        self.conversation_key = conversation_key
+        self.update = update
+        self.dispatcher = dispatcher
+
+
 class ConversationHandler(Handler):
    """
    A handler to hold a conversation with a single user by managing four collections of other
@@ -38,8 +46,10 @@ class ConversationHandler(Handler):

    The second collection, a ``dict`` named :attr:`states`, contains the different conversation
    steps and one or more associated handlers that should be used if the user sends a message when
-    the conversation with them is currently in that state. You will probably use mostly
-    :class:`telegram.ext.MessageHandler` and :class:`telegram.ext.RegexHandler` here.
+    the conversation with them is currently in that state. Here you can also define a state for
+    :attr:`TIMEOUT` to define the behavior when :attr:`conversation_timeout` is exceeded, and a
+    state for :attr:`WAITING` to define behavior when a new update is received while the previous
+    ``@run_async`` decorated handler is not finished.

    The third collection, a ``list`` named :attr:`fallbacks`, is used if the user is currently in a
    conversation but the state has either no associated handler or the handler that is associated
@@ -54,8 +64,10 @@ class ConversationHandler(Handler):

    To change the state of conversation, the callback function of a handler must return the new
    state after responding to the user. If it does not return anything (returning ``None`` by
-    default), the state will not change. To end the conversation, the callback function must
-    return :attr:`END` or ``-1``.
+    default), the state will not change. If an entry point callback function returns None,
+    the conversation ends immediately after the execution of this callback function.
+    To end the conversation, the callback function must return :attr:`END` or ``-1``. To
+    handle the conversation timeout, use handler :attr:`TIMEOUT` or ``-2``.

    Attributes:
        entry_points (List[:class:`telegram.ext.Handler`]): A list of ``Handler`` objects that can
@@ -66,19 +78,21 @@ class ConversationHandler(Handler):
        fallbacks (List[:class:`telegram.ext.Handler`]): A list of handlers that might be used if
            the user is in a conversation, but every handler for their current state returned
            ``False`` on :attr:`check_update`.
-        allow_reentry (:obj:`bool`): Optional. Determines if a user can restart a conversation with
+        allow_reentry (:obj:`bool`): Determines if a user can restart a conversation with
            an entry point.
-        run_async_timeout (:obj:`float`): Optional. The time-out for ``run_async`` decorated
-            Handlers.
-        timed_out_behavior (List[:class:`telegram.ext.Handler`]): Optional. A list of handlers that
-            might be used if the wait for ``run_async`` timed out.
-        per_chat (:obj:`bool`): Optional. If the conversationkey should contain the Chat's ID.
-        per_user (:obj:`bool`): Optional. If the conversationkey should contain the User's ID.
-        per_message (:obj:`bool`): Optional. If the conversationkey should contain the Message's
+        per_chat (:obj:`bool`): If the conversationkey should contain the Chat's ID.
+        per_user (:obj:`bool`): If the conversationkey should contain the User's ID.
+        per_message (:obj:`bool`): If the conversationkey should contain the Message's
            ID.
        conversation_timeout (:obj:`float`|:obj:`datetime.timedelta`): Optional. When this handler
            is inactive more than this timeout (in seconds), it will be automatically ended. If
-            this value is 0 (default), there will be no timeout.
+            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`.
+        name (:obj:`str`): Optional. The name for this conversationhandler. Required for
+            persistence
+        persistent (:obj:`bool`): Optional. If the conversations dict for this handler should be
+            saved. Name is required and persistence has to be set in :class:`telegram.ext.Updater`

    Args:
        entry_points (List[:class:`telegram.ext.Handler`]): A list of ``Handler`` objects that can
@@ -95,24 +109,21 @@ class ConversationHandler(Handler):
            returns ``True`` will be used. If all return ``False``, the update is not handled.
        allow_reentry (:obj:`bool`, optional): If set to ``True``, a user that is currently in a
            conversation can restart the conversation by triggering one of the entry points.
-        run_async_timeout (:obj:`float`, optional): If the previous handler for this user was
-            running asynchronously using the ``run_async`` decorator, it might not be finished when
-            the next message arrives. This timeout defines how long the conversation handler should
-            wait for the next state to be computed. The default is ``None`` which means it will
-            wait indefinitely.
-        timed_out_behavior (List[:class:`telegram.ext.Handler`], optional): A list of handlers that
-            might be used if the wait for ``run_async`` timed out. The first handler which
-            :attr:`check_update` method returns ``True`` will be used. If all return ``False``,
-            the update is not handled.
        per_chat (:obj:`bool`, optional): If the conversationkey should contain the Chat's ID.
            Default is ``True``.
        per_user (:obj:`bool`, optional): If the conversationkey should contain the User's ID.
            Default is ``True``.
        per_message (:obj:`bool`, optional): If the conversationkey should contain the Message's
            ID. Default is ``False``.
-        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.
+        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`.
+        name (:obj:`str`, optional): The name for this conversationhandler. Required for
+            persistence
+        persistent (:obj:`bool`, optional): If the conversations dict for this handler should be
+            saved. Name is required and persistence has to be set in :class:`telegram.ext.Updater`

    Raises:
        ValueError
@@ -120,35 +131,43 @@ class ConversationHandler(Handler):
    """
    END = -1
    """:obj:`int`: Used as a constant to return when a conversation is ended."""
+    TIMEOUT = -2
+    """:obj:`int`: Used as a constant to handle state when a conversation is timed out."""
+    WAITING = -3
+    """:obj:`int`: Used as a constant to handle state when a conversation is still waiting on the
+    previous ``@run_sync`` decorated running handler to finish."""

    def __init__(self,
                 entry_points,
                 states,
                 fallbacks,
                 allow_reentry=False,
-                 run_async_timeout=None,
-                 timed_out_behavior=None,
                 per_chat=True,
                 per_user=True,
                 per_message=False,
-                 conversation_timeout=None):
+                 conversation_timeout=None,
+                 name=None,
+                 persistent=False):

        self.entry_points = entry_points
        self.states = states
        self.fallbacks = fallbacks

        self.allow_reentry = allow_reentry
-        self.run_async_timeout = run_async_timeout
-        self.timed_out_behavior = timed_out_behavior
        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.timeout_jobs = dict()
        self.conversations = dict()
-        self.current_conversation = None
-        self.current_handler = None

        self.logger = logging.getLogger(__name__)

@@ -156,8 +175,8 @@ class ConversationHandler(Handler):
            raise ValueError("'per_user', 'per_chat' and 'per_message' can't all be 'False'")

        if self.per_message and not self.per_chat:
-            logging.warning("If 'per_message=True' is used, 'per_chat=True' should also be used, "
-                            "since message IDs are not globally unique.")
+            warnings.warn("If 'per_message=True' is used, 'per_chat=True' should also be used, "
+                          "since message IDs are not globally unique.")

        all_handlers = list()
        all_handlers.extend(entry_points)
@@ -169,20 +188,23 @@ class ConversationHandler(Handler):
        if self.per_message:
            for handler in all_handlers:
                if not isinstance(handler, CallbackQueryHandler):
-                    logging.warning("If 'per_message=True', all entry points and state handlers"
-                                    " must be 'CallbackQueryHandler', since no other handlers "
-                                    "have a message context.")
+                    warnings.warn("If 'per_message=True', all entry points and state handlers"
+                                  " must be 'CallbackQueryHandler', since no other handlers "
+                                  "have a message context.")
+                    break
        else:
            for handler in all_handlers:
                if isinstance(handler, CallbackQueryHandler):
-                    logging.warning("If 'per_message=False', 'CallbackQueryHandler' will not be "
-                                    "tracked for every message.")
+                    warnings.warn("If 'per_message=False', 'CallbackQueryHandler' will not be "
+                                  "tracked for every message.")
+                    break

        if self.per_chat:
            for handler in all_handlers:
                if isinstance(handler, (InlineQueryHandler, ChosenInlineResultHandler)):
-                    logging.warning("If 'per_chat=True', 'InlineQueryHandler' can not be used, "
-                                    "since inline queries have no chat context.")
+                    warnings.warn("If 'per_chat=True', 'InlineQueryHandler' can not be used, "
+                                  "since inline queries have no chat context.")
+                    break

    def _get_key(self, update):
        chat = update.effective_chat
@@ -215,44 +237,41 @@ class ConversationHandler(Handler):

        """
        # Ignore messages in channels
-        if (not isinstance(update, Update) or
-                update.channel_post or
-                self.per_chat and not update.effective_chat or
-                self.per_message and not update.callback_query or
-                update.callback_query and self.per_chat and not update.callback_query.message):
-            return False
+        if (not isinstance(update, Update)
+                or update.channel_post
+                or self.per_chat and not update.effective_chat
+                or self.per_message and not update.callback_query
+                or update.callback_query and self.per_chat and not update.callback_query.message):
+            return None

        key = self._get_key(update)
        state = self.conversations.get(key)

        # Resolve promises
-        if isinstance(state, tuple) and len(state) is 2 and isinstance(state[1], Promise):
+        if isinstance(state, tuple) and len(state) == 2 and isinstance(state[1], Promise):
            self.logger.debug('waiting for promise...')

            old_state, new_state = state
-            error = False
-            try:
-                res = new_state.result(timeout=self.run_async_timeout)
-            except Exception as exc:
-                self.logger.exception("Promise function raised exception")
-                self.logger.exception("{}".format(exc))
-                error = True
-
-            if not error and new_state.done.is_set():
-                self.update_state(res, key)
-                state = self.conversations.get(key)
-
+            if new_state.done.wait(0):
+                try:
+                    res = new_state.result(0)
+                    res = res if res is not None else old_state
+                except Exception as exc:
+                    self.logger.exception("Promise function raised exception")
+                    self.logger.exception("{}".format(exc))
+                    res = old_state
+                finally:
+                    if res is None and old_state is None:
+                        res = self.END
+                    self.update_state(res, key)
+                    state = self.conversations.get(key)
            else:
-                for candidate in (self.timed_out_behavior or []):
-                    if candidate.check_update(update):
-                        # Save the current user and the selected handler for handle_update
-                        self.current_conversation = key
-                        self.current_handler = candidate
-
-                        return True
-
-                else:
-                    return False
+                handlers = self.states.get(self.WAITING, [])
+                for handler in handlers:
+                    check = handler.check_update(update)
+                    if check is not None and check is not False:
+                        return key, handler, check
+                return None

        self.logger.debug('selecting conversation %s with state %s' % (str(key), str(state)))

@@ -261,73 +280,93 @@ class ConversationHandler(Handler):
        # Search entry points for a match
        if state is None or self.allow_reentry:
            for entry_point in self.entry_points:
-                if entry_point.check_update(update):
+                check = entry_point.check_update(update)
+                if check is not None and check is not False:
                    handler = entry_point
                    break

            else:
                if state is None:
-                    return False
+                    return None

        # Get the handler list for current state, if we didn't find one yet and we're still here
        if state is not None and not handler:
            handlers = self.states.get(state)

            for candidate in (handlers or []):
-                if candidate.check_update(update):
+                check = candidate.check_update(update)
+                if check is not None and check is not False:
                    handler = candidate
                    break

            # Find a fallback handler if all other handlers fail
            else:
                for fallback in self.fallbacks:
-                    if fallback.check_update(update):
+                    check = fallback.check_update(update)
+                    if check is not None and check is not False:
                        handler = fallback
                        break

                else:
-                    return False
+                    return None

-        # Save the current user and the selected handler for handle_update
-        self.current_conversation = key
-        self.current_handler = handler
+        return key, handler, check

-        return True
-
-    def handle_update(self, update, dispatcher):
+    def handle_update(self, update, dispatcher, check_result, context=None):
        """Send the update to the callback for the current state and Handler

        Args:
+            check_result: The result from check_update. For this handler it's a tuple of key,
+                handler, and the handler's check result.
            update (:class:`telegram.Update`): Incoming telegram update.
            dispatcher (:class:`telegram.ext.Dispatcher`): Dispatcher that originated the Update.

        """
-        new_state = self.current_handler.handle_update(update, dispatcher)
-        timeout_job = self.timeout_jobs.pop(self.current_conversation, None)
+        conversation_key, handler, check_result = check_result
+        new_state = handler.handle_update(update, dispatcher, check_result, context)
+        timeout_job = self.timeout_jobs.pop(conversation_key, None)

        if timeout_job is not None:
            timeout_job.schedule_removal()
        if self.conversation_timeout and new_state != self.END:
-            self.timeout_jobs[self.current_conversation] = dispatcher.job_queue.run_once(
+            self.timeout_jobs[conversation_key] = dispatcher.job_queue.run_once(
                self._trigger_timeout, self.conversation_timeout,
-                context=self.current_conversation
-            )
+                context=_ConversationTimeoutContext(conversation_key, update, dispatcher))

-        self.update_state(new_state, self.current_conversation)
+        self.update_state(new_state, conversation_key)

    def update_state(self, new_state, key):
        if new_state == self.END:
            if key in self.conversations:
+                # If there is no key in conversations, nothing is done.
                del self.conversations[key]
-            else:
-                pass
+                if self.persistent:
+                    self.persistence.update_conversation(self.name, key, None)

        elif isinstance(new_state, Promise):
            self.conversations[key] = (self.conversations.get(key), new_state)
+            if self.persistent:
+                self.persistence.update_conversation(self.name, key,
+                                                     (self.conversations.get(key), new_state))

        elif new_state is not None:
            self.conversations[key] = new_state
+            if self.persistent:
+                self.persistence.update_conversation(self.name, key, new_state)

-    def _trigger_timeout(self, bot, job):
-        del self.timeout_jobs[job.context]
-        self.update_state(self.END, job.context)
+    def _trigger_timeout(self, context, job=None):
+        self.logger.debug('conversation timeout was triggered!')
+
+        # Backward compatibility with bots that do not use CallbackContext
+        if isinstance(context, CallbackContext):
+            context = context.job.context
+        else:
+            context = job.context
+
+        del self.timeout_jobs[context.conversation_key]
+        handlers = self.states.get(self.TIMEOUT, [])
+        for handler in handlers:
+            check = handler.check_update(context.update)
+            if check is not None and check is not False:
+                handler.handle_update(context.update, context.dispatcher, check)
+        self.update_state(self.END, context.conversation_key)
@@ -0,0 +1,196 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2018
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the DictPersistence class."""
+from copy import deepcopy
+
+from telegram.utils.helpers import decode_user_chat_data_from_json,\
+    decode_conversations_from_json, enocde_conversations_to_json
+
+try:
+    import ujson as json
+except ImportError:
+    import json
+from collections import defaultdict
+from telegram.ext import BasePersistence
+
+
+class DictPersistence(BasePersistence):
+    """Using python's dicts and json for making you bot persistent.
+
+    Attributes:
+        store_user_data (:obj:`bool`): Whether user_data should be saved by this
+            persistence class.
+        store_chat_data (:obj:`bool`): Whether chat_data should be saved by this
+            persistence class.
+
+    Args:
+        store_user_data (:obj:`bool`, optional): Whether user_data should be saved by this
+            persistence class. Default is ``True``.
+        store_chat_data (:obj:`bool`, optional): Whether user_data should be saved by this
+            persistence class. Default is ``True``.
+        user_data_json (:obj:`str`, optional): Json string that will be used to reconstruct
+            user_data on creating this persistence. Default is ``""``.
+        chat_data_json (:obj:`str`, optional): Json string that will be used to reconstruct
+            chat_data on creating this persistence. Default is ``""``.
+        conversations_json (:obj:`str`, optional): Json string that will be used to reconstruct
+            conversation on creating this persistence. Default is ``""``.
+    """
+
+    def __init__(self, store_user_data=True, store_chat_data=True, user_data_json='',
+                 chat_data_json='', conversations_json=''):
+        self.store_user_data = store_user_data
+        self.store_chat_data = store_chat_data
+        self._user_data = None
+        self._chat_data = None
+        self._conversations = None
+        self._user_data_json = None
+        self._chat_data_json = None
+        self._conversations_json = None
+        if user_data_json:
+            try:
+                self._user_data = decode_user_chat_data_from_json(user_data_json)
+                self._user_data_json = user_data_json
+            except (ValueError, AttributeError):
+                raise TypeError("Unable to deserialize user_data_json. Not valid JSON")
+        if chat_data_json:
+            try:
+                self._chat_data = decode_user_chat_data_from_json(chat_data_json)
+                self._chat_data_json = chat_data_json
+            except (ValueError, AttributeError):
+                raise TypeError("Unable to deserialize chat_data_json. Not valid JSON")
+
+        if conversations_json:
+            try:
+                self._conversations = decode_conversations_from_json(conversations_json)
+                self._conversations_json = conversations_json
+            except (ValueError, AttributeError):
+                raise TypeError("Unable to deserialize conversations_json. Not valid JSON")
+
+    @property
+    def user_data(self):
+        """:obj:`dict`: The user_data as a dict"""
+        return self._user_data
+
+    @property
+    def user_data_json(self):
+        """:obj:`str`: The user_data serialized as a JSON-string."""
+        if self._user_data_json:
+            return self._user_data_json
+        else:
+            return json.dumps(self.user_data)
+
+    @property
+    def chat_data(self):
+        """:obj:`dict`: The chat_data as a dict"""
+        return self._chat_data
+
+    @property
+    def chat_data_json(self):
+        """:obj:`str`: The chat_data serialized as a JSON-string."""
+        if self._chat_data_json:
+            return self._chat_data_json
+        else:
+            return json.dumps(self.chat_data)
+
+    @property
+    def conversations(self):
+        """:obj:`dict`: The conversations as a dict"""
+        return self._conversations
+
+    @property
+    def conversations_json(self):
+        """:obj:`str`: The conversations serialized as a JSON-string."""
+        if self._conversations_json:
+            return self._conversations_json
+        else:
+            return enocde_conversations_to_json(self.conversations)
+
+    def get_user_data(self):
+        """Returns the user_data created from the ``user_data_json`` or an empty defaultdict.
+
+        Returns:
+            :obj:`defaultdict`: The restored user data.
+        """
+        if self.user_data:
+            pass
+        else:
+            self._user_data = defaultdict(dict)
+        return deepcopy(self.user_data)
+
+    def get_chat_data(self):
+        """Returns the chat_data created from the ``chat_data_json`` or an empty defaultdict.
+
+        Returns:
+            :obj:`defaultdict`: The restored user data.
+        """
+        if self.chat_data:
+            pass
+        else:
+            self._chat_data = defaultdict(dict)
+        return deepcopy(self.chat_data)
+
+    def get_conversations(self, name):
+        """Returns the conversations created from the ``conversations_json`` or an empty
+        defaultdict.
+
+        Returns:
+            :obj:`defaultdict`: The restored user data.
+        """
+        if self.conversations:
+            pass
+        else:
+            self._conversations = {}
+        return self.conversations.get(name, {}).copy()
+
+    def update_conversation(self, name, key, new_state):
+        """Will update the conversations for the given handler.
+
+        Args:
+            name (:obj:`str`): The handlers name.
+            key (:obj:`tuple`): The key the state is changed for.
+            new_state (:obj:`tuple` | :obj:`any`): The new state for the given key.
+        """
+        if self._conversations.setdefault(name, {}).get(key) == new_state:
+            return
+        self._conversations[name][key] = new_state
+        self._conversations_json = None
+
+    def update_user_data(self, user_id, data):
+        """Will update the user_data (if changed).
+
+        Args:
+            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.get(user_id) == data:
+            return
+        self._user_data[user_id] = data
+        self._user_data_json = None
+
+    def update_chat_data(self, chat_id, data):
+        """Will update the chat_data (if changed).
+
+        Args:
+            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.get(chat_id) == data:
+            return
+        self._chat_data[chat_id] = data
+        self._chat_data_json = None
@@ -19,6 +19,7 @@
 """This module contains the Dispatcher class."""

 import logging
+import warnings
 import weakref
 from functools import wraps
 from threading import Thread, Lock, Event, current_thread, BoundedSemaphore
@@ -30,24 +31,30 @@ from queue import Queue, Empty

 from future.builtins import range

-from telegram import TelegramError
+from telegram import TelegramError, Update
 from telegram.ext.handler import Handler
+from telegram.ext.callbackcontext import CallbackContext
+from telegram.utils.deprecate import TelegramDeprecationWarning
 from telegram.utils.promise import Promise
+from telegram.ext import BasePersistence

 logging.getLogger(__name__).addHandler(logging.NullHandler())
 DEFAULT_GROUP = 0


 def run_async(func):
-    """Function decorator that will run the function in a new thread.
+    """
+    Function decorator that will run the function in a new thread.

    Will run :attr:`telegram.ext.Dispatcher.run_async`.

    Using this decorator is only possible when only a single Dispatcher exist in the system.

-    Note: Use this decorator to run handlers asynchronously.
-
+    Warning:
+        If you're using @run_async you cannot rely on adding custom attributes to
+        :class:`telegram.ext.CallbackContext`. See its docs for more info.
    """
+
    @wraps(func)
    def async_func(*args, **kwargs):
        return Dispatcher.get_instance().run_async(func, *args, **kwargs)
@@ -70,6 +77,10 @@ class Dispatcher(object):
            instance to pass onto handler callbacks.
        workers (:obj:`int`): Number of maximum concurrent worker threads for the ``@run_async``
            decorator.
+        user_data (:obj:`defaultdict`): A dictionary handlers can use to store data for the user.
+        chat_data (:obj:`defaultdict`): A dictionary handlers can use to store data for the chat.
+        persistence (:class:`telegram.ext.BasePersistence`): Optional. The persistence class to
+            store data that should be persistent over restarts

    Args:
        bot (:class:`telegram.Bot`): The bot object that should be passed to the handlers.
@@ -78,6 +89,11 @@ class Dispatcher(object):
                instance to pass onto handler callbacks.
        workers (:obj:`int`, optional): Number of maximum concurrent worker threads for the
            ``@run_async`` decorator. defaults to 4.
+        persistence (:class:`telegram.ext.BasePersistence`, optional): The persistence class to
+            store data that should be persistent over restarts
+        use_context (:obj:`bool`, optional): If set to ``True`` Use the context based callback API.
+            During the deprecation period of the old API the default is ``False``. **New users**:
+            set this to ``True``.

    """

@@ -86,16 +102,44 @@ class Dispatcher(object):
    __singleton = None
    logger = logging.getLogger(__name__)

-    def __init__(self, bot, update_queue, workers=4, exception_event=None, job_queue=None):
+    def __init__(self,
+                 bot,
+                 update_queue,
+                 workers=4,
+                 exception_event=None,
+                 job_queue=None,
+                 persistence=None,
+                 use_context=False):
        self.bot = bot
        self.update_queue = update_queue
        self.job_queue = job_queue
        self.workers = workers
+        self.use_context = use_context
+
+        if not use_context:
+            warnings.warn('Old Handler API is deprecated - see https://git.io/fxJuV for details',
+                          TelegramDeprecationWarning, stacklevel=3)

        self.user_data = defaultdict(dict)
        """:obj:`dict`: A dictionary handlers can use to store data for the user."""
        self.chat_data = defaultdict(dict)
-        """:obj:`dict`: A dictionary handlers can use to store data for the chat."""
+        if persistence:
+            if not isinstance(persistence, BasePersistence):
+                raise TypeError("persistence should be based on telegram.ext.BasePersistence")
+            self.persistence = persistence
+            if self.persistence.store_user_data:
+                self.user_data = self.persistence.get_user_data()
+                if not isinstance(self.user_data, defaultdict):
+                    raise ValueError("user_data must be of type defaultdict")
+            if self.persistence.store_chat_data:
+                self.chat_data = self.persistence.get_chat_data()
+                if not isinstance(self.chat_data, defaultdict):
+                    raise ValueError("chat_data must be of type defaultdict")
+        else:
+            self.persistence = None
+
+        self.job_queue = job_queue
+
        self.handlers = {}
        """Dict[:obj:`int`, List[:class:`telegram.ext.Handler`]]: Holds the handlers per group."""
        self.groups = []
@@ -122,7 +166,8 @@ class Dispatcher(object):
        base_name = '{}_'.format(base_name) if base_name else ''

        for i in range(workers):
-            thread = Thread(target=self._pooled, name='{}{}'.format(base_name, i))
+            thread = Thread(target=self._pooled, name='Bot:{}:worker:{}{}'.format(self.bot.id,
+                                                                                  base_name, i))
            self.__async_threads.add(thread)
            thread.start()

@@ -168,6 +213,10 @@ class Dispatcher(object):
    def run_async(self, func, *args, **kwargs):
        """Queue a function (with given args/kwargs) to be run asynchronously.

+        Warning:
+            If you're using @run_async you cannot rely on adding custom attributes to
+            :class:`telegram.ext.CallbackContext`. See its docs for more info.
+
        Args:
            func (:obj:`callable`): The function to run in the thread.
            *args (:obj:`tuple`, optional): Arguments to `func`.
@@ -226,6 +275,7 @@ class Dispatcher(object):

            self.logger.debug('Processing Update: %s' % update)
            self.process_update(update)
+            self.update_queue.task_done()

        self.running = False
        self.logger.debug('Dispatcher thread stopped')
@@ -265,6 +315,43 @@ class Dispatcher(object):
                The update to process.

        """
+
+        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_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:
@@ -273,32 +360,37 @@ class Dispatcher(object):
                self.logger.exception('An uncaught error was raised while handling the error')
            return

+        context = None
+
        for group in self.groups:
            try:
-                for handler in (x for x in self.handlers[group] if x.check_update(update)):
-                    handler.handle_update(update, self)
-                    break
+                for handler in self.handlers[group]:
+                    check = handler.check_update(update)
+                    if check is not None and check is not False:
+                        if not context and self.use_context:
+                            context = CallbackContext.from_update(update, self)
+                        handler.handle_update(update, self, check, context)
+                        persist_update(update)
+                        break

            # Stop processing with any other handler.
            except DispatcherHandlerStop:
                self.logger.debug('Stopping further handlers due to DispatcherHandlerStop')
+                persist_update(update)
                break

            # Dispatch any error.
-            except TelegramError as te:
-                self.logger.warning('A TelegramError was raised while processing the Update')
-
+            except Exception as e:
                try:
-                    self.dispatch_error(update, te)
+                    self.dispatch_error(update, e)
                except DispatcherHandlerStop:
                    self.logger.debug('Error handler stopped further handlers')
                    break
+                # Errors should not stop the thread.
                except Exception:
-                    self.logger.exception('An uncaught error was raised while handling the error')
-
-            # Errors should not stop the thread.
-            except Exception:
-                self.logger.exception('An uncaught error was raised while processing the update')
+                    self.logger.exception('An error was raised while processing the update and an '
+                                          'uncaught error was raised while handling the error '
+                                          'with an error_handler')

    def add_handler(self, handler, group=DEFAULT_GROUP):
        """Register a handler.
@@ -324,11 +416,20 @@ class Dispatcher(object):
            group (:obj:`int`, optional): The group identifier. Default is 0.

        """
+        # Unfortunately due to circular imports this has to be here
+        from .conversationhandler import ConversationHandler

        if not isinstance(handler, Handler):
            raise TypeError('handler is not an instance of {0}'.format(Handler.__name__))
        if not isinstance(group, int):
            raise TypeError('group is not int')
+        if isinstance(handler, ConversationHandler) and handler.persistent:
+            if not self.persistence:
+                raise ValueError(
+                    "Conversationhandler {} can not be persistent if dispatcher has no "
+                    "persistence".format(handler.name))
+            handler.conversations = self.persistence.get_conversations(handler.name)
+            handler.persistence = self.persistence

        if group not in self.handlers:
            self.handlers[group] = list()
@@ -351,13 +452,34 @@ class Dispatcher(object):
                del self.handlers[group]
                self.groups.remove(group)

+    def update_persistence(self):
+        """Update :attr:`user_data` and :attr:`chat_data` in :attr:`persistence`.
+        """
+        if self.persistence:
+            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])
+            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])
+
    def add_error_handler(self, callback):
-        """Registers an error handler in the Dispatcher.
+        """Registers an error handler in the Dispatcher. This handler will receive every error
+        which happens in your bot.
+
+        Warning: The errors handled within these handlers won't show up in the logger, so you
+        need to make sure that you reraise the error.

        Args:
-            callback (:obj:`callable`): A function that takes ``Bot, Update, TelegramError`` as
-                arguments.
+            callback (:obj:`callable`): The callback function for this error handler. Will be
+                called when an error is raised. Callback signature for context based API:

+                ``def callback(update: Update, context: CallbackContext)``
+
+                The error that happened will be present in context.error.
+
+        Note:
+            See https://git.io/fxJuV for more info about switching to context based API.
        """
        self.error_handlers.append(callback)

@@ -376,12 +498,15 @@ class Dispatcher(object):

        Args:
            update (:obj:`str` | :class:`telegram.Update` | None): The update that caused the error
-            error (:class:`telegram.TelegramError`): The Telegram error that was raised.
+            error (:obj:`Exception`): The error that was raised.

        """
        if self.error_handlers:
            for callback in self.error_handlers:
-                callback(self.bot, update, error)
+                if self.use_context:
+                    callback(update, CallbackContext.from_error(update, error, self))
+                else:
+                    callback(self.bot, update, error)

        else:
            self.logger.exception(
@@ -19,9 +19,13 @@
 """This module contains the Filters for use with the MessageHandler class."""

 import re
-from telegram import Chat
+
 from future.utils import string_types

+from telegram import Chat
+
+__all__ = ['Filters', 'BaseFilter', 'InvertedFilter', 'MergedFilter']
+

 class BaseFilter(object):
    """Base class for all Message Filters.
@@ -45,6 +49,16 @@ class BaseFilter(object):
        >>> (Filters.text & (Filters.entity(URL) | Filters.entity(TEXT_LINK)))
        >>> Filters.text & (~ Filters.forwarded)

+    Note:
+        Filters use the same short circuiting logic that pythons `and`, `or` and `not`.
+        This means that for example:
+
+            >>> Filters.regex(r'(a?x)') | Filters.regex(r'(b?x)')
+
+        With a message.text of `x`, will only ever return the matches for the first filter,
+        since the second one is never evaluated.
+
+
    If you want to create your own filters create a class inheriting from this class and implement
    a `filter` method that returns a boolean: `True` if the message should be handled, `False`
    otherwise. Note that the filters work only as class instances, not actual class objects
@@ -56,13 +70,23 @@ class BaseFilter(object):

    Attributes:
        name (:obj:`str`): Name for this filter. Defaults to the type of filter.
-
+        update_filter (:obj:`bool`): Whether this filter should work on update. If ``False`` it
+            will run the filter on :attr:`update.effective_message``. Default is ``False``.
+        data_filter (:obj:`bool`): Whether this filter is a data filter. A data filter should
+            return a dict with lists. The dict will be merged with
+            :class:`telegram.ext.CallbackContext`'s internal dict in most cases
+            (depends on the handler).
    """

    name = None
+    update_filter = False
+    data_filter = False

-    def __call__(self, message):
-        return self.filter(message)
+    def __call__(self, update):
+        if self.update_filter:
+            return self.filter(update)
+        else:
+            return self.filter(update.effective_message)

    def __and__(self, other):
        return MergedFilter(self, and_filter=other)
@@ -79,14 +103,18 @@ class BaseFilter(object):
            self.name = self.__class__.__name__
        return self.name

-    def filter(self, message):
+    def filter(self, update):
        """This method must be overwritten.

+        Note:
+            If :attr:`update_filter` is false then the first argument is `message` and of
+            type :class:`telegram.Message`.
+
        Args:
-            message (:class:`telegram.Message`): The message that is tested.
+            update (:class:`telegram.Update`): The update that is tested.

        Returns:
-            :obj:`bool`
+            :obj:`dict` or :obj:`bool`

        """

@@ -100,12 +128,13 @@ class InvertedFilter(BaseFilter):
        f: The filter to invert.

    """
+    update_filter = True

    def __init__(self, f):
        self.f = f

-    def filter(self, message):
-        return not self.f(message)
+    def filter(self, update):
+        return not bool(self.f(update))

    def __repr__(self):
        return "<inverted {}>".format(self.f)
@@ -120,17 +149,66 @@ class MergedFilter(BaseFilter):
        or_filter: Optional filter to "or" with base_filter. Mutually exclusive with and_filter.

    """
+    update_filter = True

    def __init__(self, base_filter, and_filter=None, or_filter=None):
        self.base_filter = base_filter
+        if self.base_filter.data_filter:
+            self.data_filter = True
        self.and_filter = and_filter
+        if (self.and_filter
+                and not isinstance(self.and_filter, bool)
+                and self.and_filter.data_filter):
+            self.data_filter = True
        self.or_filter = or_filter
+        if (self.or_filter
+                and not isinstance(self.and_filter, bool)
+                and self.or_filter.data_filter):
+            self.data_filter = True

-    def filter(self, message):
+    def _merge(self, base_output, comp_output):
+        base = base_output if isinstance(base_output, dict) else {}
+        comp = comp_output if isinstance(comp_output, dict) else {}
+        for k in comp.keys():
+            # Make sure comp values are lists
+            comp_value = comp[k] if isinstance(comp[k], list) else []
+            try:
+                # If base is a list then merge
+                if isinstance(base[k], list):
+                    base[k] += comp_value
+                else:
+                    base[k] = [base[k]] + comp_value
+            except KeyError:
+                base[k] = comp_value
+        return base
+
+    def filter(self, update):
+        base_output = self.base_filter(update)
+        # We need to check if the filters are data filters and if so return the merged data.
+        # If it's not a data filter or an or_filter but no matches return bool
        if self.and_filter:
-            return self.base_filter(message) and self.and_filter(message)
+            # And filter needs to short circuit if base is falsey
+            if base_output:
+                comp_output = self.and_filter(update)
+                if comp_output:
+                    if self.data_filter:
+                        merged = self._merge(base_output, comp_output)
+                        if merged:
+                            return merged
+                    return True
        elif self.or_filter:
-            return self.base_filter(message) or self.or_filter(message)
+            # Or filter needs to short circuit if base is truthey
+            if base_output:
+                if self.data_filter:
+                    return base_output
+                return True
+            else:
+                comp_output = self.or_filter(update)
+                if comp_output:
+                    if self.data_filter:
+                        return comp_output
+                    return True
+        return False

    def __repr__(self):
        return "<{} {} {}>".format(self.base_filter, "and" if self.and_filter else "or",
@@ -153,7 +231,7 @@ class Filters(object):
            return True

    all = _All()
-    """:obj:`Filter`: All Messages."""
+    """All Messages."""

    class _Text(BaseFilter):
        name = 'Filters.text'
@@ -162,7 +240,7 @@ class Filters(object):
            return bool(message.text and not message.text.startswith('/'))

    text = _Text()
-    """:obj:`Filter`: Text Messages."""
+    """Text Messages."""

    class _Command(BaseFilter):
        name = 'Filters.command'
@@ -171,36 +249,52 @@ class Filters(object):
            return bool(message.text and message.text.startswith('/'))

    command = _Command()
-    """:obj:`Filter`: Messages starting with ``/``."""
+    """Messages starting with ``/``."""

    class regex(BaseFilter):
        """
-        Filters updates by searching for an occurence of ``pattern`` in the message text.
+        Filters updates by searching for an occurrence of ``pattern`` in the message text.
        The ``re.search`` function is used to determine whether an update should be filtered.
+
        Refer to the documentation of the ``re`` module for more information.

-        Note: Does not allow passing groups or a groupdict like the ``RegexHandler`` yet,
-        but this will probably be implemented in a future update, gradually phasing out the
-        RegexHandler (see https://github.com/python-telegram-bot/python-telegram-bot/issues/835).
+        To get the groups and groupdict matched, see :attr:`telegram.ext.CallbackContext.matches`.

        Examples:
-            Example ``CommandHandler("start", deep_linked_callback, Filters.regex('parameter'))``
+            Use ``MessageHandler(Filters.regex(r'help'), callback)`` to capture all messages that
+            contain the word help. You can also use
+            ``MessageHandler(Filters.regex(re.compile(r'help', re.IGNORECASE), callback)`` if
+            you want your pattern to be case insensitive. This approach is recommended
+            if you need to specify flags on your pattern.
+
+        Note:
+            Filters use the same short circuiting logic that pythons `and`, `or` and `not`.
+            This means that for example:
+
+                >>> Filters.regex(r'(a?x)') | Filters.regex(r'(b?x)')
+
+            With a message.text of `x`, will only ever return the matches for the first filter,
+            since the second one is never evaluated.

        Args:
            pattern (:obj:`str` | :obj:`Pattern`): The regex pattern.
        """

+        data_filter = True
+
        def __init__(self, pattern):
-            self.pattern = re.compile(pattern)
+            if isinstance(pattern, string_types):
+                pattern = re.compile(pattern)
+            self.pattern = pattern
            self.name = 'Filters.regex({})'.format(self.pattern)

-        # TODO: Once the callback revamp (#1026) is done, the regex filter should be able to pass
-        # the matched groups and groupdict to the context object.
-
        def filter(self, message):
+            """"""  # remove method from docs
            if message.text:
-                return bool(self.pattern.search(message.text))
-            return False
+                match = self.pattern.search(message.text)
+                if match:
+                    return {'matches': [match]}
+                return {}

    class _Reply(BaseFilter):
        name = 'Filters.reply'
@@ -209,7 +303,7 @@ class Filters(object):
            return bool(message.reply_to_message)

    reply = _Reply()
-    """:obj:`Filter`: Messages that are a reply to another message."""
+    """Messages that are a reply to another message."""

    class _Audio(BaseFilter):
        name = 'Filters.audio'
@@ -218,7 +312,7 @@ class Filters(object):
            return bool(message.audio)

    audio = _Audio()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Audio`."""
+    """Messages that contain :class:`telegram.Audio`."""

    class _Document(BaseFilter):
        name = 'Filters.document'
@@ -232,7 +326,7 @@ class Filters(object):
                The user can manipulate the mime-type of a message and
                    send media with wrong types that don't fit to this handler.

-            Examples:
+            Example:
                Filters.documents.category('audio/') returnes `True` for all types
                of audio sent as file, for example 'audio/mpeg' or 'audio/x-wav'
            """
@@ -246,6 +340,7 @@ class Filters(object):
                self.name = "Filters.document.category('{}')".format(self.category)

            def filter(self, message):
+                """"""  # remove method from docs
                if message.document:
                    return message.document.mime_type.startswith(self.category)

@@ -264,8 +359,8 @@ class Filters(object):
                The user can manipulate the mime-type of a message and
                    send media with wrong types that don't fit to this handler.

-            Examples:
-                Filters.documents.mime_type('audio/mpeg') filters all audio in mp3 format.
+            Example:
+                ``Filters.documents.mime_type('audio/mpeg')`` filters all audio in mp3 format.
            """

            def __init__(self, mimetype):
@@ -277,6 +372,7 @@ class Filters(object):
                self.name = "Filters.document.mime_type('{}')".format(self.mimetype)

            def filter(self, message):
+                """"""  # remove method from docs
                if message.document:
                    return message.document.mime_type == self.mimetype

@@ -300,7 +396,91 @@ class Filters(object):
            return bool(message.document)

    document = _Document()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Document`."""
+    """
+    Subset for messages containing a document/file.
+
+    Examples:
+        Use these filters like: ``Filters.document.mp3``,
+        ``Filters.document.mime_type("text/plain")`` etc. Or use just
+        ``Filters.document`` for all document messages.
+
+    Attributes:
+        category: This Filter filters documents by their category in the mime-type attribute.
+
+            Example:
+                ``Filters.documents.category('audio/')`` filters all types
+                of audio sent as file, for example 'audio/mpeg' or 'audio/x-wav'. The following
+                attributes can be used as a shortcut like: ``Filters.document.audio``
+
+        application:
+        audio:
+        image:
+        video:
+        text:
+        mime_type: This Filter filters documents by their mime-type attribute.
+
+            Example:
+                ``Filters.documents.mime_type('audio/mpeg')`` filters all audio in mp3 format. The
+                following attributes can be used as a shortcut like: ``Filters.document.jpg``
+        apk:
+        doc:
+        docx:
+        exe:
+        gif:
+        jpg:
+        mp3:
+        pdf:
+        py:
+        svg:
+        txt:
+        targz:
+        wav:
+        xml:
+        zip:
+        category: This Filter filters documents by their category in the mime-type attribute
+
+            Note:
+                This Filter only filters by the mime_type of the document,
+                it doesn't check the validity of the document.
+                The user can manipulate the mime-type of a message and
+                send media with wrong types that don't fit to this handler.
+
+            Example:
+                ``Filters.documents.category('audio/')`` filters all types
+                of audio sent as file, for example 'audio/mpeg' or 'audio/x-wav'
+        application: Same as ``Filters.document.category("application")``.
+        audio: Same as ``Filters.document.category("audio")``.
+        image: Same as ``Filters.document.category("image")``.
+        video: Same as ``Filters.document.category("video")``.
+        text: Same as ``Filters.document.category("text")``.
+        mime_type: This Filter filters documents by their mime-type attribute
+
+            Note:
+                This Filter only filters by the mime_type of the document,
+                it doesn't check the validity of document.
+
+                The user can manipulate the mime-type of a message and
+                send media with wrong types that don't fit to this handler.
+
+            Example:
+                ``Filters.documents.mime_type('audio/mpeg')`` filters all audio in mp3 format.
+        apk: Same as ``Filters.document.mime_type("application/vnd.android.package-archive")``-
+        doc: Same as ``Filters.document.mime_type("application/msword")``-
+        docx: Same as ``Filters.document.mime_type("application/vnd.openxmlformats-\
+officedocument.wordprocessingml.document")``-
+        exe: Same as ``Filters.document.mime_type("application/x-ms-dos-executable")``-
+        gif: Same as ``Filters.document.mime_type("video/mp4")``-
+        jpg: Same as ``Filters.document.mime_type("image/jpeg")``-
+        mp3: Same as ``Filters.document.mime_type("audio/mpeg")``-
+        pdf: Same as ``Filters.document.mime_type("application/pdf")``-
+        py: Same as ``Filters.document.mime_type("text/x-python")``-
+        svg: Same as ``Filters.document.mime_type("image/svg+xml")``-
+        txt: Same as ``Filters.document.mime_type("text/plain")``-
+        targz: Same as ``Filters.document.mime_type("application/x-compressed-tar")``-
+        wav: Same as ``Filters.document.mime_type("audio/x-wav")``-
+        xml: Same as ``Filters.document.mime_type("application/xml")``-
+        zip: Same as ``Filters.document.mime_type("application/zip")``-
+    """

    class _Animation(BaseFilter):
        name = 'Filters.animation'
@@ -309,7 +489,7 @@ class Filters(object):
            return bool(message.animation)

    animation = _Animation()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Animation`."""
+    """Messages that contain :class:`telegram.Animation`."""

    class _Photo(BaseFilter):
        name = 'Filters.photo'
@@ -318,7 +498,7 @@ class Filters(object):
            return bool(message.photo)

    photo = _Photo()
-    """:obj:`Filter`: Messages that contain :class:`telegram.PhotoSize`."""
+    """Messages that contain :class:`telegram.PhotoSize`."""

    class _Sticker(BaseFilter):
        name = 'Filters.sticker'
@@ -327,7 +507,7 @@ class Filters(object):
            return bool(message.sticker)

    sticker = _Sticker()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Sticker`."""
+    """Messages that contain :class:`telegram.Sticker`."""

    class _Video(BaseFilter):
        name = 'Filters.video'
@@ -336,7 +516,7 @@ class Filters(object):
            return bool(message.video)

    video = _Video()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Video`."""
+    """Messages that contain :class:`telegram.Video`."""

    class _Voice(BaseFilter):
        name = 'Filters.voice'
@@ -345,7 +525,7 @@ class Filters(object):
            return bool(message.voice)

    voice = _Voice()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Voice`."""
+    """Messages that contain :class:`telegram.Voice`."""

    class _VideoNote(BaseFilter):
        name = 'Filters.video_note'
@@ -354,7 +534,7 @@ class Filters(object):
            return bool(message.video_note)

    video_note = _VideoNote()
-    """:obj:`Filter`: Messages that contain :class:`telegram.VideoNote`."""
+    """Messages that contain :class:`telegram.VideoNote`."""

    class _Contact(BaseFilter):
        name = 'Filters.contact'
@@ -363,7 +543,7 @@ class Filters(object):
            return bool(message.contact)

    contact = _Contact()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Contact`."""
+    """Messages that contain :class:`telegram.Contact`."""

    class _Location(BaseFilter):
        name = 'Filters.location'
@@ -372,7 +552,7 @@ class Filters(object):
            return bool(message.location)

    location = _Location()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Location`."""
+    """Messages that contain :class:`telegram.Location`."""

    class _Venue(BaseFilter):
        name = 'Filters.venue'
@@ -381,7 +561,7 @@ class Filters(object):
            return bool(message.venue)

    venue = _Venue()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Venue`."""
+    """Messages that contain :class:`telegram.Venue`."""

    class _StatusUpdate(BaseFilter):
        """Subset for messages containing a status update.
@@ -391,6 +571,7 @@ class Filters(object):
            ``Filters.status_update`` for all status update messages.

        """
+        update_filter = True

        class _NewChatMembers(BaseFilter):
            name = 'Filters.status_update.new_chat_members'
@@ -399,7 +580,7 @@ class Filters(object):
                return bool(message.new_chat_members)

        new_chat_members = _NewChatMembers()
-        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.new_chat_members`."""
+        """Messages that contain :attr:`telegram.Message.new_chat_members`."""

        class _LeftChatMember(BaseFilter):
            name = 'Filters.status_update.left_chat_member'
@@ -408,7 +589,7 @@ class Filters(object):
                return bool(message.left_chat_member)

        left_chat_member = _LeftChatMember()
-        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.left_chat_member`."""
+        """Messages that contain :attr:`telegram.Message.left_chat_member`."""

        class _NewChatTitle(BaseFilter):
            name = 'Filters.status_update.new_chat_title'
@@ -417,7 +598,7 @@ class Filters(object):
                return bool(message.new_chat_title)

        new_chat_title = _NewChatTitle()
-        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.new_chat_title`."""
+        """Messages that contain :attr:`telegram.Message.new_chat_title`."""

        class _NewChatPhoto(BaseFilter):
            name = 'Filters.status_update.new_chat_photo'
@@ -426,7 +607,7 @@ class Filters(object):
                return bool(message.new_chat_photo)

        new_chat_photo = _NewChatPhoto()
-        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.new_chat_photo`."""
+        """Messages that contain :attr:`telegram.Message.new_chat_photo`."""

        class _DeleteChatPhoto(BaseFilter):
            name = 'Filters.status_update.delete_chat_photo'
@@ -435,17 +616,17 @@ class Filters(object):
                return bool(message.delete_chat_photo)

        delete_chat_photo = _DeleteChatPhoto()
-        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.delete_chat_photo`."""
+        """Messages that contain :attr:`telegram.Message.delete_chat_photo`."""

        class _ChatCreated(BaseFilter):
            name = 'Filters.status_update.chat_created'

            def filter(self, message):
-                return bool(message.group_chat_created or message.supergroup_chat_created or
-                            message.channel_chat_created)
+                return bool(message.group_chat_created or message.supergroup_chat_created
+                            or message.channel_chat_created)

        chat_created = _ChatCreated()
-        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.group_chat_created`,
+        """Messages that contain :attr:`telegram.Message.group_chat_created`,
            :attr: `telegram.Message.supergroup_chat_created` or
            :attr: `telegram.Message.channel_chat_created`."""

@@ -456,7 +637,7 @@ class Filters(object):
                return bool(message.migrate_from_chat_id or message.migrate_to_chat_id)

        migrate = _Migrate()
-        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.migrate_from_chat_id` or
+        """Messages that contain :attr:`telegram.Message.migrate_from_chat_id` or
            :attr: `telegram.Message.migrate_to_chat_id`."""

        class _PinnedMessage(BaseFilter):
@@ -466,7 +647,7 @@ class Filters(object):
                return bool(message.pinned_message)

        pinned_message = _PinnedMessage()
-        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.pinned_message`."""
+        """Messages that contain :attr:`telegram.Message.pinned_message`."""

        class _ConnectedWebsite(BaseFilter):
            name = 'Filters.status_update.connected_website'
@@ -475,16 +656,16 @@ class Filters(object):
                return bool(message.connected_website)

        connected_website = _ConnectedWebsite()
-        """:obj:`Filter`: Messages that contain :attr:`telegram.Message.connected_website`."""
+        """Messages that contain :attr:`telegram.Message.connected_website`."""

        name = 'Filters.status_update'

        def filter(self, message):
-            return bool(self.new_chat_members(message) or self.left_chat_member(message) or
-                        self.new_chat_title(message) or self.new_chat_photo(message) or
-                        self.delete_chat_photo(message) or self.chat_created(message) or
-                        self.migrate(message) or self.pinned_message(message) or
-                        self.connected_website(message))
+            return bool(self.new_chat_members(message) or self.left_chat_member(message)
+                        or self.new_chat_title(message) or self.new_chat_photo(message)
+                        or self.delete_chat_photo(message) or self.chat_created(message)
+                        or self.migrate(message) or self.pinned_message(message)
+                        or self.connected_website(message))

    status_update = _StatusUpdate()
    """Subset for messages containing a status update.
@@ -494,24 +675,24 @@ class Filters(object):
        ``Filters.status_update`` for all status update messages.

    Attributes:
-        chat_created (:obj:`Filter`): Messages that contain
+        chat_created: Messages that contain
            :attr:`telegram.Message.group_chat_created`,
            :attr:`telegram.Message.supergroup_chat_created` or
            :attr:`telegram.Message.channel_chat_created`.
-        delete_chat_photo (:obj:`Filter`): Messages that contain
+        delete_chat_photo: Messages that contain
            :attr:`telegram.Message.delete_chat_photo`.
-        left_chat_member (:obj:`Filter`): Messages that contain
+        left_chat_member: Messages that contain
            :attr:`telegram.Message.left_chat_member`.
-        migrate (:obj:`Filter`): Messages that contain
+        migrate: Messages that contain
            :attr:`telegram.Message.migrate_from_chat_id` or
            :attr: `telegram.Message.migrate_from_chat_id`.
-        new_chat_members (:obj:`Filter`): Messages that contain
+        new_chat_members: Messages that contain
            :attr:`telegram.Message.new_chat_members`.
-        new_chat_photo (:obj:`Filter`): Messages that contain
+        new_chat_photo: Messages that contain
            :attr:`telegram.Message.new_chat_photo`.
-        new_chat_title (:obj:`Filter`): Messages that contain
+        new_chat_title: Messages that contain
            :attr:`telegram.Message.new_chat_title`.
-        pinned_message (:obj:`Filter`): Messages that contain
+        pinned_message: Messages that contain
            :attr:`telegram.Message.pinned_message`.
    """

@@ -522,7 +703,7 @@ class Filters(object):
            return bool(message.forward_date)

    forwarded = _Forwarded()
-    """:obj:`Filter`: Messages that are forwarded."""
+    """Messages that are forwarded."""

    class _Game(BaseFilter):
        name = 'Filters.game'
@@ -531,7 +712,7 @@ class Filters(object):
            return bool(message.game)

    game = _Game()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Game`."""
+    """Messages that contain :class:`telegram.Game`."""

    class entity(BaseFilter):
        """
@@ -552,6 +733,7 @@ class Filters(object):
            self.name = 'Filters.entity({})'.format(self.entity_type)

        def filter(self, message):
+            """"""  # remove method from docs
            return any(entity.type == self.entity_type for entity in message.entities)

    class caption_entity(BaseFilter):
@@ -573,6 +755,7 @@ class Filters(object):
            self.name = 'Filters.caption_entity({})'.format(self.entity_type)

        def filter(self, message):
+            """"""  # remove method from docs
            return any(entity.type == self.entity_type for entity in message.caption_entities)

    class _Private(BaseFilter):
@@ -582,7 +765,7 @@ class Filters(object):
            return message.chat.type == Chat.PRIVATE

    private = _Private()
-    """:obj:`Filter`: Messages sent in a private chat."""
+    """Messages sent in a private chat."""

    class _Group(BaseFilter):
        name = 'Filters.group'
@@ -591,7 +774,7 @@ class Filters(object):
            return message.chat.type in [Chat.GROUP, Chat.SUPERGROUP]

    group = _Group()
-    """:obj:`Filter`: Messages sent in a group chat."""
+    """Messages sent in a group chat."""

    class user(BaseFilter):
        """Filters messages to allow only those which are from specified user ID.
@@ -624,12 +807,13 @@ class Filters(object):
                self.usernames = [user.replace('@', '') for user in username]

        def filter(self, message):
+            """"""  # remove method from docs
            if self.user_ids is not None:
                return bool(message.from_user and message.from_user.id in self.user_ids)
            else:
                # self.usernames is not None
-                return bool(message.from_user and message.from_user.username and
-                            message.from_user.username in self.usernames)
+                return bool(message.from_user and message.from_user.username
+                            and message.from_user.username in self.usernames)

    class chat(BaseFilter):
        """Filters messages to allow only those which are from specified chat ID.
@@ -662,6 +846,7 @@ class Filters(object):
                self.usernames = [chat.replace('@', '') for chat in username]

        def filter(self, message):
+            """"""  # remove method from docs
            if self.chat_ids is not None:
                return bool(message.chat_id in self.chat_ids)
            else:
@@ -675,7 +860,7 @@ class Filters(object):
            return bool(message.invoice)

    invoice = _Invoice()
-    """:obj:`Filter`: Messages that contain :class:`telegram.Invoice`."""
+    """Messages that contain :class:`telegram.Invoice`."""

    class _SuccessfulPayment(BaseFilter):
        name = 'Filters.successful_payment'
@@ -684,7 +869,7 @@ class Filters(object):
            return bool(message.successful_payment)

    successful_payment = _SuccessfulPayment()
-    """:obj:`Filter`: Messages that confirm a :class:`telegram.SuccessfulPayment`."""
+    """Messages that confirm a :class:`telegram.SuccessfulPayment`."""

    class _PassportData(BaseFilter):
        name = 'Filters.passport_data'
@@ -693,13 +878,14 @@ class Filters(object):
            return bool(message.passport_data)

    passport_data = _PassportData()
-    """:obj:`Filter`: Messages that contain a :class:`telegram.PassportData`"""
+    """Messages that contain a :class:`telegram.PassportData`"""

    class language(BaseFilter):
        """Filters messages to only allow those which are from users with a certain language code.

-        Note: According to telegrams documentation, every single user does not have the
-        `language_code` attribute.
+        Note:
+            According to official telegram api documentation, not every single user has the
+            `language_code` attribute. Do not count on this filter working on all users.

        Examples:
            ``MessageHandler(Filters.language("en"), callback_method)``
@@ -719,5 +905,80 @@ class Filters(object):
            self.name = 'Filters.language({})'.format(self.lang)

        def filter(self, message):
+            """"""  # remove method from docs
            return message.from_user.language_code and any(
                [message.from_user.language_code.startswith(x) for x in self.lang])
+
+    class _UpdateType(BaseFilter):
+        update_filter = True
+
+        class _Message(BaseFilter):
+            update_filter = True
+
+            def filter(self, update):
+                return update.message is not None
+
+        message = _Message()
+
+        class _EditedMessage(BaseFilter):
+            update_filter = True
+
+            def filter(self, update):
+                return update.edited_message is not None
+
+        edited_message = _EditedMessage()
+
+        class _Messages(BaseFilter):
+            update_filter = True
+
+            def filter(self, update):
+                return update.message is not None or update.edited_message is not None
+
+        messages = _Messages()
+
+        class _ChannelPost(BaseFilter):
+            update_filter = True
+
+            def filter(self, update):
+                return update.channel_post is not None
+
+        channel_post = _ChannelPost()
+
+        class _EditedChannelPost(BaseFilter):
+            update_filter = True
+
+            def filter(self, update):
+                return update.edited_channel_post is not None
+
+        edited_channel_post = _EditedChannelPost()
+
+        class _ChannelPosts(BaseFilter):
+            update_filter = True
+
+            def filter(self, update):
+                return update.channel_post is not None or update.edited_channel_post is not None
+
+        channel_posts = _ChannelPosts()
+
+        def filter(self, update):
+            return self.messages(update) or self.channel_posts(update)
+
+    update = _UpdateType()
+    """Subset for filtering the type of update.
+
+    Examples:
+        Use these filters like: ``Filters.update.message`` or
+        ``Filters.update.channel_posts`` etc. Or use just ``Filters.update`` for all
+        types.
+
+    Attributes:
+        message: Updates with :attr:`telegram.Update.message`
+        edited_message: Updates with :attr:`telegram.Update.edited_message`
+        messages: Updates with either :attr:`telegram.Update.message` or
+            :attr:`telegram.Update.edited_message`
+        channel_post: Updates with :attr:`telegram.Update.channel_post`
+        edited_channel_post: Updates with
+            :attr:`telegram.Update.edited_channel_post`
+        channel_posts: Updates with either :attr:`telegram.Update.channel_post` or
+            :attr:`telegram.Update.edited_channel_post`
+    """
@@ -24,13 +24,13 @@ class Handler(object):

    Attributes:
        callback (:obj:`callable`): The callback function for this handler.
-        pass_update_queue (:obj:`bool`): Optional. Determines whether ``update_queue`` will be
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Optional. Determines whether ``job_queue`` will be passed to
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
            the callback function.
-        pass_user_data (:obj:`bool`): Optional. Determines whether ``user_data`` will be passed to
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
            the callback function.
-        pass_chat_data (:obj:`bool`): Optional. Determines whether ``chat_data`` will be passed to
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
            the callback function.

    Note:
@@ -39,22 +39,34 @@ class Handler(object):
        either the user or the chat that the update was sent in. For each update from the same user
        or in the same chat, it will be the same ``dict``.

+        Note that this is DEPRECATED, and you should use context based callbacks. See
+        https://git.io/fxJuV for more info.
+
    Args:
-        callback (:obj:`callable`): A function that takes ``bot, update`` as positional arguments.
-            It will be called when the :attr:`check_update` has determined that an update should be
-            processed by this handler.
+        callback (:obj:`callable`): The callback function for this handler. Will be called when
+            :attr:`check_update` has determined that an update should be processed by this handler.
+            Callback signature for context based API:
+
+            ``def callback(update: Update, context: CallbackContext)``
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
        pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
            instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
            that contains new updates which can be used to insert updates. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``job_queue`` will be passed to the callback function. It will be a
            :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
            which can be used to schedule new jobs. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``user_data`` will be passed to the callback function. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``chat_data`` will be passed to the callback function. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.

    """

@@ -79,31 +91,58 @@ class Handler(object):
            update (:obj:`str` | :class:`telegram.Update`): The update to be tested.

        Returns:
-            :obj:`bool`
+            Either ``None`` or ``False`` if the update should not be handled. Otherwise an object
+            that will be passed to :attr:`handle_update` and :attr:`collect_additional_context`
+            when the update gets handled.

        """
        raise NotImplementedError

-    def handle_update(self, update, dispatcher):
+    def handle_update(self, update, dispatcher, check_result, context=None):
        """
        This method is called if it was determined that an update should indeed
-        be handled by this instance. It should also be overridden, but in most
-        cases call ``self.callback(dispatcher.bot, update)``, possibly along with
-        optional arguments. To work with the ``ConversationHandler``, this method should return the
-        value returned from ``self.callback``
+        be handled by this instance. Calls :attr:`self.callback` along with its respectful
+        arguments. To work with the :class:`telegram.ext.ConversationHandler`, this method
+        returns the value returned from ``self.callback``.
+        Note that it can be overridden if needed by the subclassing handler.

        Args:
            update (:obj:`str` | :class:`telegram.Update`): The update to be handled.
-            dispatcher (:class:`telegram.ext.Dispatcher`): The dispatcher to collect optional args.
+            dispatcher (:class:`telegram.ext.Dispatcher`): The calling dispatcher.
+            check_result: The result from :attr:`check_update`.

        """
-        raise NotImplementedError
+        if context:
+            self.collect_additional_context(context, update, dispatcher, check_result)
+            return self.callback(update, context)
+        else:
+            optional_args = self.collect_optional_args(dispatcher, update, check_result)
+            return self.callback(dispatcher.bot, update, **optional_args)

-    def collect_optional_args(self, dispatcher, update=None):
-        """Prepares the optional arguments that are the same for all types of handlers.
+    def collect_additional_context(self, context, update, dispatcher, check_result):
+        """Prepares additional arguments for the context. Override if needed.
+
+        Args:
+            context (:class:`telegram.ext.CallbackContext`): The context object.
+            update (:class:`telegram.Update`): The update to gather chat/user id from.
+            dispatcher (:class:`telegram.ext.Dispatcher`): The calling dispatcher.
+            check_result: The result (return value) from :attr:`check_update`.
+
+        """
+        pass
+
+    def collect_optional_args(self, dispatcher, update=None, check_result=None):
+        """
+        Prepares the optional arguments. If the handler has additional optional args,
+        it should subclass this method, but remember to call this super method.
+
+        DEPRECATED: This method is being replaced by new context based callbacks. Please see
+        https://git.io/fxJuV for more info.

        Args:
            dispatcher (:class:`telegram.ext.Dispatcher`): The dispatcher.
+            update (:class:`telegram.Update`): The update to gather chat/user id from.
+            check_result: The result from check_update

        """
        optional_args = dict()
@@ -22,7 +22,6 @@ import re
 from future.utils import string_types

 from telegram import Update
-from telegram.utils.deprecate import deprecate
 from .handler import Handler


@@ -33,19 +32,19 @@ class InlineQueryHandler(Handler):

    Attributes:
        callback (:obj:`callable`): The callback function for this handler.
-        pass_update_queue (:obj:`bool`): Optional. Determines whether ``update_queue`` will be
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Optional. Determines whether ``job_queue`` will be passed to
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
            the callback function.
        pattern (:obj:`str` | :obj:`Pattern`): Optional. Regex pattern to test
            :attr:`telegram.InlineQuery.query` against.
-        pass_groups (:obj:`bool`): Optional. Determines whether ``groups`` will be passed to the
+        pass_groups (:obj:`bool`): Determines whether ``groups`` will be passed to the
            callback function.
-        pass_groupdict (:obj:`bool`): Optional. Determines whether ``groupdict``. will be passed to
+        pass_groupdict (:obj:`bool`): Determines whether ``groupdict``. will be passed to
            the callback function.
-        pass_user_data (:obj:`bool`): Optional. Determines whether ``user_data`` will be passed to
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
            the callback function.
-        pass_chat_data (:obj:`bool`): Optional. Determines whether ``chat_data`` will be passed to
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
            the callback function.

    Note:
@@ -54,31 +53,46 @@ class InlineQueryHandler(Handler):
        either the user or the chat that the update was sent in. For each update from the same user
        or in the same chat, it will be the same ``dict``.

+        Note that this is DEPRECATED, and you should use context based callbacks. See
+        https://git.io/fxJuV for more info.
+
    Args:
-        callback (:obj:`callable`): A function that takes ``bot, update`` as positional arguments.
-            It will be called when the :attr:`check_update` has determined that an update should be
-            processed by this handler.
+        callback (:obj:`callable`): The callback function for this handler. Will be called when
+            :attr:`check_update` has determined that an update should be processed by this handler.
+            Callback signature for context based API:
+
+            ``def callback(update: Update, context: CallbackContext)``
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
        pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
            instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
            that contains new updates which can be used to insert updates. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``job_queue`` will be passed to the callback function. It will be a
            :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
            which can be used to schedule new jobs. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pattern (:obj:`str` | :obj:`Pattern`, optional): Regex pattern. If not ``None``,
            ``re.match`` is used on :attr:`telegram.InlineQuery.query` to determine if an update
            should be handled by this handler.
        pass_groups (:obj:`bool`, optional): If the callback should be passed the result of
            ``re.match(pattern, data).groups()`` as a keyword argument called ``groups``.
            Default is ``False``
+            DEPRECATED: Please switch to context based callbacks.
        pass_groupdict (:obj:`bool`, optional): If the callback should be passed the result of
            ``re.match(pattern, data).groupdict()`` as a keyword argument called ``groupdict``.
            Default is ``False``
+            DEPRECATED: Please switch to context based callbacks.
        pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``user_data`` will be passed to the callback function. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``chat_data`` will be passed to the callback function. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
+
    """

    def __init__(self,
@@ -113,37 +127,28 @@ class InlineQueryHandler(Handler):

        Returns:
            :obj:`bool`
+
        """

        if isinstance(update, Update) and update.inline_query:
            if self.pattern:
                if update.inline_query.query:
                    match = re.match(self.pattern, update.inline_query.query)
-                    return bool(match)
+                    if match:
+                        return match
            else:
                return True

-    def handle_update(self, update, dispatcher):
-        """
-        Send the update to the :attr:`callback`.
-
-        Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
-            dispatcher (:class:`telegram.ext.Dispatcher`): Dispatcher that originated the Update.
-        """
-
-        optional_args = self.collect_optional_args(dispatcher, update)
+    def collect_optional_args(self, dispatcher, update=None, check_result=None):
+        optional_args = super(InlineQueryHandler, self).collect_optional_args(dispatcher,
+                                                                              update, check_result)
        if self.pattern:
-            match = re.match(self.pattern, update.inline_query.query)
-
            if self.pass_groups:
-                optional_args['groups'] = match.groups()
+                optional_args['groups'] = check_result.groups()
            if self.pass_groupdict:
-                optional_args['groupdict'] = match.groupdict()
+                optional_args['groupdict'] = check_result.groupdict()
+        return optional_args

-        return self.callback(dispatcher.bot, update, **optional_args)
-
-    # old non-PEP8 Handler methods
-    m = "telegram.InlineQueryHandler."
-    checkUpdate = deprecate(check_update, m + "checkUpdate", m + "check_update")
-    handleUpdate = deprecate(handle_update, m + "handleUpdate", m + "handle_update")
+    def collect_additional_context(self, context, update, dispatcher, check_result):
+        if self.pattern:
+            context.matches = [check_result]
@@ -18,13 +18,17 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains the classes JobQueue and Job."""

+import datetime
 import logging
 import time
-import datetime
+import warnings
 import weakref
 from numbers import Number
-from threading import Thread, Lock, Event
 from queue import PriorityQueue, Empty
+from threading import Thread, Lock, Event
+
+from telegram.ext.callbackcontext import CallbackContext
+from telegram.utils.deprecate import TelegramDeprecationWarning


 class Days(object):
@@ -37,16 +41,24 @@ class JobQueue(object):

    Attributes:
        _queue (:obj:`PriorityQueue`): The queue that holds the Jobs.
-        bot (:class:`telegram.Bot`): Bot that's send to the handlers.
-
-    Args:
        bot (:class:`telegram.Bot`): The bot instance that should be passed to the jobs.
-
+            DEPRECATED: Use set_dispatcher instead.
    """

-    def __init__(self, bot):
+    def __init__(self, bot=None):
        self._queue = PriorityQueue()
-        self.bot = bot
+        if bot:
+            warnings.warn("Passing bot to jobqueue is deprecated. Please use set_dispatcher "
+                          "instead!", TelegramDeprecationWarning, stacklevel=2)
+
+            class MockDispatcher(object):
+                def __init__(self):
+                    self.bot = bot
+                    self.use_context = False
+
+            self._dispatcher = MockDispatcher()
+        else:
+            self._dispatcher = None
        self.logger = logging.getLogger(self.__class__.__name__)
        self.__start_lock = Lock()
        self.__next_peek_lock = Lock()  # to protect self._next_peek & self.__tick
@@ -55,6 +67,9 @@ class JobQueue(object):
        self._next_peek = None
        self._running = False

+    def set_dispatcher(self, dispatcher):
+        self._dispatcher = dispatcher
+
    def _put(self, job, next_t=None, last_t=None):
        if next_t is None:
            next_t = job.interval
@@ -90,7 +105,7 @@ class JobQueue(object):
        Args:
            callback (:obj:`callable`): The callback function that should be executed by the new
                job. It should take ``bot, job`` as parameters, where ``job`` is the
-                :class:`telegram.ext.Job` instance. It can be used to access it's
+                :class:`telegram.ext.Job` instance. It can be used to access its
                ``job.context`` or change it to a repeating job.
            when (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta` |                         \
                  :obj:`datetime.datetime` | :obj:`datetime.time`):
@@ -122,12 +137,12 @@ class JobQueue(object):
        return job

    def run_repeating(self, callback, interval, first=None, context=None, name=None):
-        """Creates a new ``Job`` that runs once and adds it to the queue.
+        """Creates a new ``Job`` that runs at specified intervals and adds it to the queue.

        Args:
            callback (:obj:`callable`): The callback function that should be executed by the new
                job. It should take ``bot, job`` as parameters, where ``job`` is the
-                :class:`telegram.ext.Job` instance. It can be used to access it's
+                :class:`telegram.ext.Job` instance. It can be used to access its
                ``Job.context`` or change it to a repeating job.
            interval (:obj:`int` | :obj:`float` | :obj:`datetime.timedelta`): The interval in which
                the job will run. If it is an :obj:`int` or a :obj:`float`, it will be interpreted
@@ -157,6 +172,11 @@ class JobQueue(object):
            :class:`telegram.ext.Job`: The new ``Job`` instance that has been added to the job
            queue.

+        Notes:
+             `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.
+
        """
        job = Job(callback,
                  interval=interval,
@@ -168,12 +188,12 @@ class JobQueue(object):
        return job

    def run_daily(self, callback, time, days=Days.EVERY_DAY, context=None, name=None):
-        """Creates a new ``Job`` that runs once and adds it to the queue.
+        """Creates a new ``Job`` that runs on a daily basis and adds it to the queue.

        Args:
            callback (:obj:`callable`): The callback function that should be executed by the new
                job. It should take ``bot, job`` as parameters, where ``job`` is the
-                :class:`telegram.ext.Job` instance. It can be used to access it's ``Job.context``
+                :class:`telegram.ext.Job` instance. It can be used to access its ``Job.context``
                or change it to a repeating job.
            time (:obj:`datetime.time`): Time of day at which the job should run.
            days (Tuple[:obj:`int`], optional): Defines on which days of the week the job should
@@ -187,6 +207,11 @@ class JobQueue(object):
            :class:`telegram.ext.Job`: The new ``Job`` instance that has been added to the job
            queue.

+        Notes:
+             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.
+
        """
        job = Job(callback,
                  interval=datetime.timedelta(days=1),
@@ -242,7 +267,7 @@ class JobQueue(object):
                    current_week_day = datetime.datetime.now().weekday()
                    if any(day == current_week_day for day in job.days):
                        self.logger.debug('Running job %s', job.name)
-                        job.run(self.bot)
+                        job.run(self._dispatcher)

                except Exception:
                    self.logger.exception('An uncaught error was raised while executing job %s',
@@ -262,7 +287,8 @@ class JobQueue(object):
        if not self._running:
            self._running = True
            self.__start_lock.release()
-            self.__thread = Thread(target=self._main_loop, name="job_queue")
+            self.__thread = Thread(target=self._main_loop,
+                                   name="Bot:{}:job_queue".format(self._dispatcher.bot.id))
            self.__thread.start()
            self.logger.debug('%s thread started', self.__class__.__name__)
        else:
@@ -367,9 +393,12 @@ class Job(object):
        self._enabled = Event()
        self._enabled.set()

-    def run(self, bot):
+    def run(self, dispatcher):
        """Executes the callback function."""
-        self.callback(bot, self)
+        if dispatcher.use_context:
+            self.callback(CallbackContext.from_job(self, dispatcher))
+        else:
+            self.callback(dispatcher.bot, self)

    def schedule_removal(self):
        """
@@ -20,7 +20,10 @@
 """This module contains the MessageHandler class."""
 import warnings

+from telegram.utils.deprecate import TelegramDeprecationWarning
+
 from telegram import Update
+from telegram.ext import Filters
 from .handler import Handler


@@ -31,22 +34,20 @@ class MessageHandler(Handler):
        filters (:obj:`Filter`): Only allow updates with these Filters. See
            :mod:`telegram.ext.filters` for a full list of all available filters.
        callback (:obj:`callable`): The callback function for this handler.
-        pass_update_queue (:obj:`bool`): Optional. Determines whether ``update_queue`` will be
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Optional. Determines whether ``job_queue`` will be passed to
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
            the callback function.
-        pass_user_data (:obj:`bool`): Optional. Determines whether ``user_data`` will be passed to
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
            the callback function.
-        pass_chat_data (:obj:`bool`): Optional. Determines whether ``chat_data`` will be passed to
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
            the callback function.
-        message_updates (:obj:`bool`): Optional. Should "normal" message updates be handled?
-            Default is ``True``.
-        channel_post_updates (:obj:`bool`): Optional. Should channel posts updates be handled?
-            Default is ``True``.
-        edited_updates (:obj:`bool`): Optional. Should "edited" message updates be handled?
-            Default is ``False``.
-        allow_edited (:obj:`bool`): Optional. If the handler should also accept edited messages.
-            Default is ``False`` - Deprecated. use edited_updates instead.
+        message_updates (:obj:`bool`): Should "normal" message updates be handled?
+            Default is ``None``.
+        channel_post_updates (:obj:`bool`): Should channel posts updates be handled?
+            Default is ``None``.
+        edited_updates (:obj:`bool`): Should "edited" message updates be handled?
+            Default is ``None``.

    Note:
        :attr:`pass_user_data` and :attr:`pass_chat_data` determine whether a ``dict`` you
@@ -54,34 +55,51 @@ class MessageHandler(Handler):
        either the user or the chat that the update was sent in. For each update from the same user
        or in the same chat, it will be the same ``dict``.

+        Note that this is DEPRECATED, and you should use context based callbacks. See
+        https://git.io/fxJuV for more info.
+
    Args:
        filters (:class:`telegram.ext.BaseFilter`, optional): A filter inheriting from
            :class:`telegram.ext.filters.BaseFilter`. Standard filters can be found in
            :class:`telegram.ext.filters.Filters`. Filters can be combined using bitwise
-            operators (& for and, | for or, ~ for not).
-        callback (:obj:`callable`): A function that takes ``bot, update`` as positional arguments.
-            It will be called when the :attr:`check_update` has determined that an update should be
-            processed by this handler.
+            operators (& for and, | for or, ~ for not). Default is
+            :attr:`telegram.ext.filters.Filters.update`. This defaults to all message_type updates
+            being: ``message``, ``edited_message``, ``channel_post`` and ``edited_channel_post``.
+            If you don't want or need any of those pass ``~Filters.update.*`` in the filter
+            argument.
+        callback (:obj:`callable`): The callback function for this handler. Will be called when
+            :attr:`check_update` has determined that an update should be processed by this handler.
+            Callback signature for context based API:
+
+            ``def callback(update: Update, context: CallbackContext)``
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
        pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
            instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
            that contains new updates which can be used to insert updates. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``job_queue`` will be passed to the callback function. It will be a
            :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
            which can be used to schedule new jobs. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``user_data`` will be passed to the callback function. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``chat_data`` will be passed to the callback function. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        message_updates (:obj:`bool`, optional): Should "normal" message updates be handled?
-            Default is ``True``.
+            Default is ``None``.
+            DEPRECATED: Please switch to filters for update filtering.
        channel_post_updates (:obj:`bool`, optional): Should channel posts updates be handled?
-            Default is ``True``.
+            Default is ``None``.
+            DEPRECATED: Please switch to filters for update filtering.
        edited_updates (:obj:`bool`, optional): Should "edited" message updates be handled? Default
-            is ``False``.
-        allow_edited (:obj:`bool`, optional): If the handler should also accept edited messages.
-            Default is ``False`` - Deprecated. use edited_updates instead.
+            is ``None``.
+            DEPRECATED: Please switch to filters for update filtering.

    Raises:
        ValueError
@@ -91,20 +109,13 @@ class MessageHandler(Handler):
    def __init__(self,
                 filters,
                 callback,
-                 allow_edited=False,
                 pass_update_queue=False,
                 pass_job_queue=False,
                 pass_user_data=False,
                 pass_chat_data=False,
-                 message_updates=True,
-                 channel_post_updates=True,
-                 edited_updates=False):
-        if not message_updates and not channel_post_updates and not edited_updates:
-            raise ValueError(
-                'message_updates, channel_post_updates and edited_updates are all False')
-        if allow_edited:
-            warnings.warn('allow_edited is getting deprecated, please use edited_updates instead')
-            edited_updates = allow_edited
+                 message_updates=None,
+                 channel_post_updates=None,
+                 edited_updates=None):

        super(MessageHandler, self).__init__(
            callback,
@@ -112,22 +123,36 @@ class MessageHandler(Handler):
            pass_job_queue=pass_job_queue,
            pass_user_data=pass_user_data,
            pass_chat_data=pass_chat_data)
+        if message_updates is False and channel_post_updates is False and edited_updates is False:
+            raise ValueError(
+                'message_updates, channel_post_updates and edited_updates are all False')
        self.filters = filters
-        self.message_updates = message_updates
-        self.channel_post_updates = channel_post_updates
-        self.edited_updates = edited_updates
+        if self.filters is not None:
+            self.filters &= Filters.update
+        else:
+            self.filters = Filters.update
+        if message_updates is not None:
+            warnings.warn('message_updates is deprecated. See https://git.io/fxJuV for more info',
+                          TelegramDeprecationWarning,
+                          stacklevel=2)
+            if message_updates is False:
+                self.filters &= ~Filters.update.message

-        # We put this up here instead of with the rest of checking code
-        # in check_update since we don't wanna spam a ton
-        if isinstance(self.filters, list):
-            warnings.warn('Using a list of filters in MessageHandler is getting '
-                          'deprecated, please use bitwise operators (& and |) '
-                          'instead. More info: https://git.io/vPTbc.')
+        if channel_post_updates is not None:
+            warnings.warn('channel_post_updates is deprecated. See https://git.io/fxJuV '
+                          'for more info',
+                          TelegramDeprecationWarning,
+                          stacklevel=2)
+            if channel_post_updates is False:
+                self.filters &= ~Filters.update.channel_post

-    def _is_allowed_update(self, update):
-        return any([self.message_updates and update.message,
-                    self.edited_updates and (update.edited_message or update.edited_channel_post),
-                    self.channel_post_updates and update.channel_post])
+        if edited_updates is not None:
+            warnings.warn('edited_updates is deprecated. See https://git.io/fxJuV for more info',
+                          TelegramDeprecationWarning,
+                          stacklevel=2)
+            if edited_updates is False:
+                self.filters &= ~(Filters.update.edited_message
+                                  | Filters.update.edited_channel_post)

    def check_update(self, update):
        """Determines whether an update should be passed to this handlers :attr:`callback`.
@@ -139,31 +164,9 @@ class MessageHandler(Handler):
            :obj:`bool`

        """
-        if isinstance(update, Update) and self._is_allowed_update(update):
+        if isinstance(update, Update) and update.effective_message:
+            return self.filters(update)

-            if not self.filters:
-                res = True
-
-            else:
-                message = update.effective_message
-                if isinstance(self.filters, list):
-                    res = any(func(message) for func in self.filters)
-                else:
-                    res = self.filters(message)
-
-        else:
-            res = False
-
-        return res
-
-    def handle_update(self, update, dispatcher):
-        """Send the update to the :attr:`callback`.
-
-        Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
-            dispatcher (:class:`telegram.ext.Dispatcher`): Dispatcher that originated the Update.
-
-        """
-        optional_args = self.collect_optional_args(dispatcher, update)
-
-        return self.callback(dispatcher.bot, update, **optional_args)
+    def collect_additional_context(self, context, update, dispatcher, check_result):
+        if isinstance(check_result, dict):
+            context.update(check_result)
@@ -247,7 +247,7 @@ class MessageQueue(object):
            is_group_msg (:obj:`bool`, optional): Defines whether ``promise`` would be processed in
                group*+*all* ``DelayQueue``s (if set to ``True``), or only through *all*
                ``DelayQueue`` (if set to ``False``), resulting in needed delays to avoid
-                hitting specified limits. Defaults to ``True``.
+                hitting specified limits. Defaults to ``False``.

        Notes:
            Method is designed to accept ``telegram.utils.promise.Promise`` as ``promise``
@@ -0,0 +1,236 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2018
+# Leandro Toledo de Souza <devs@python-telegram-bot.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser Public License for more details.
+#
+# You should have received a copy of the GNU Lesser Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+"""This module contains the PicklePersistence class."""
+import pickle
+from collections import defaultdict
+from copy import deepcopy
+
+from telegram.ext import BasePersistence
+
+
+class PicklePersistence(BasePersistence):
+    """Using python's builtin pickle for making you bot persistent.
+
+    Attributes:
+        filename (:obj:`str`): The filename for storing the pickle files. When :attr:`single_file`
+            is false this will be used as a prefix.
+        store_user_data (:obj:`bool`): Optional. Whether user_data should be saved by this
+            persistence class.
+        store_chat_data (:obj:`bool`): Optional. Whether user_data should be saved by this
+            persistence class.
+        single_file (:obj:`bool`): Optional. When ``False`` will store 3 sperate files of
+            `filename_user_data`, `filename_chat_data` and `filename_conversations`. Default is
+            ``True``.
+        on_flush (:obj:`bool`, optional): When ``True`` will only save to file when :meth:`flush`
+            is called and keep data in memory until that happens. When ``False`` will store data
+            on any transaction *and* on call fo :meth:`flush`. Default is ``False``.
+
+    Args:
+        filename (:obj:`str`): The filename for storing the pickle files. When :attr:`single_file`
+            is false this will be used as a prefix.
+        store_user_data (:obj:`bool`, optional): Whether user_data should be saved by this
+            persistence class. Default is ``True``.
+        store_chat_data (:obj:`bool`, optional): Whether user_data should be saved by this
+            persistence class. Default is ``True``.
+        single_file (:obj:`bool`, optional): When ``False`` will store 3 sperate files of
+            `filename_user_data`, `filename_chat_data` and `filename_conversations`. Default is
+            ``True``.
+        on_flush (:obj:`bool`, optional): When ``True`` will only save to file when :meth:`flush`
+            is called and keep data in memory until that happens. When ``False`` will store data
+            on any transaction *and* on call fo :meth:`flush`. Default is ``False``.
+    """
+
+    def __init__(self, filename, store_user_data=True, store_chat_data=True, single_file=True,
+                 on_flush=False):
+        self.filename = filename
+        self.store_user_data = store_user_data
+        self.store_chat_data = store_chat_data
+        self.single_file = single_file
+        self.on_flush = on_flush
+        self.user_data = None
+        self.chat_data = None
+        self.conversations = None
+
+    def load_singlefile(self):
+        try:
+            filename = self.filename
+            with open(self.filename, "rb") as f:
+                all = pickle.load(f)
+                self.user_data = defaultdict(dict, all['user_data'])
+                self.chat_data = defaultdict(dict, all['chat_data'])
+                self.conversations = all['conversations']
+        except IOError:
+            self.conversations = {}
+            self.user_data = defaultdict(dict)
+            self.chat_data = defaultdict(dict)
+        except pickle.UnpicklingError:
+            raise TypeError("File {} does not contain valid pickle data".format(filename))
+        except Exception:
+            raise TypeError("Something went wrong unpickling {}".format(filename))
+
+    def load_file(self, filename):
+        try:
+            with open(filename, "rb") as f:
+                return pickle.load(f)
+        except IOError:
+            return None
+        except pickle.UnpicklingError:
+            raise TypeError("File {} does not contain valid pickle data".format(filename))
+        except Exception:
+            raise TypeError("Something went wrong unpickling {}".format(filename))
+
+    def dump_singlefile(self):
+        with open(self.filename, "wb") as f:
+            all = {'conversations': self.conversations, 'user_data': self.user_data,
+                   'chat_data': self.chat_data}
+            pickle.dump(all, f)
+
+    def dump_file(self, filename, data):
+        with open(filename, "wb") as f:
+            pickle.dump(data, f)
+
+    def get_user_data(self):
+        """Returns the user_data from the pickle file if it exsists or an empty defaultdict.
+
+        Returns:
+            :obj:`defaultdict`: The restored user data.
+        """
+        if self.user_data:
+            pass
+        elif not self.single_file:
+            filename = "{}_user_data".format(self.filename)
+            data = self.load_file(filename)
+            if not data:
+                data = defaultdict(dict)
+            else:
+                data = defaultdict(dict, data)
+            self.user_data = data
+        else:
+            self.load_singlefile()
+        return deepcopy(self.user_data)
+
+    def get_chat_data(self):
+        """Returns the chat_data from the pickle file if it exsists or an empty defaultdict.
+
+        Returns:
+            :obj:`defaultdict`: The restored chat data.
+        """
+        if self.chat_data:
+            pass
+        elif not self.single_file:
+            filename = "{}_chat_data".format(self.filename)
+            data = self.load_file(filename)
+            if not data:
+                data = defaultdict(dict)
+            else:
+                data = defaultdict(dict, data)
+            self.chat_data = data
+        else:
+            self.load_singlefile()
+        return deepcopy(self.chat_data)
+
+    def get_conversations(self, name):
+        """Returns the conversations from the pickle file if it exsists or an empty defaultdict.
+
+        Args:
+            name (:obj:`str`): The handlers name.
+
+        Returns:
+            :obj:`dict`: The restored conversations for the handler.
+        """
+        if self.conversations:
+            pass
+        elif not self.single_file:
+            filename = "{}_conversations".format(self.filename)
+            data = self.load_file(filename)
+            if not data:
+                data = {name: {}}
+            self.conversations = data
+        else:
+            self.load_singlefile()
+        return self.conversations.get(name, {}).copy()
+
+    def update_conversation(self, name, key, new_state):
+        """Will update the conversations for the given handler and depending on :attr:`on_flush`
+        save the pickle file.
+
+        Args:
+            name (:obj:`str`): The handlers name.
+            key (:obj:`tuple`): The key the state is changed for.
+            new_state (:obj:`tuple` | :obj:`any`): The new state for the given key.
+        """
+        if self.conversations.setdefault(name, {}).get(key) == new_state:
+            return
+        self.conversations[name][key] = new_state
+        if not self.on_flush:
+            if not self.single_file:
+                filename = "{}_conversations".format(self.filename)
+                self.dump_file(filename, self.conversations)
+            else:
+                self.dump_singlefile()
+
+    def update_user_data(self, user_id, data):
+        """Will update the user_data (if changed) and depending on :attr:`on_flush` save the
+        pickle file.
+
+        Args:
+            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.get(user_id) == data:
+            return
+        self.user_data[user_id] = data
+        if not self.on_flush:
+            if not self.single_file:
+                filename = "{}_user_data".format(self.filename)
+                self.dump_file(filename, self.user_data)
+            else:
+                self.dump_singlefile()
+
+    def update_chat_data(self, chat_id, data):
+        """Will update the chat_data (if changed) and depending on :attr:`on_flush` save the
+        pickle file.
+
+        Args:
+            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.get(chat_id) == data:
+            return
+        self.chat_data[chat_id] = data
+        if not self.on_flush:
+            if not self.single_file:
+                filename = "{}_chat_data".format(self.filename)
+                self.dump_file(filename, self.chat_data)
+            else:
+                self.dump_singlefile()
+
+    def flush(self):
+        """ Will save all data in memory to pickle file(s).
+        """
+        if self.single_file:
+            if self.user_data or self.chat_data or self.conversations:
+                self.dump_singlefile()
+        else:
+            if self.user_data:
+                self.dump_file("{}_user_data".format(self.filename), self.user_data)
+            if self.chat_data:
+                self.dump_file("{}_chat_data".format(self.filename), self.chat_data)
+            if self.conversations:
+                self.dump_file("{}_conversations".format(self.filename), self.conversations)
@@ -27,13 +27,13 @@ class PreCheckoutQueryHandler(Handler):

    Attributes:
        callback (:obj:`callable`): The callback function for this handler.
-        pass_update_queue (:obj:`bool`): Optional. Determines whether ``update_queue`` will be
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Optional. Determines whether ``job_queue`` will be passed to
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
            the callback function.
-        pass_user_data (:obj:`bool`): Optional. Determines whether ``user_data`` will be passed to
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
            the callback function.
-        pass_chat_data (:obj:`bool`): Optional. Determines whether ``chat_data`` will be passed to
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
            the callback function.

    Note:
@@ -42,38 +42,37 @@ class PreCheckoutQueryHandler(Handler):
        either the user or the chat that the update was sent in. For each update from the same user
        or in the same chat, it will be the same ``dict``.

+        Note that this is DEPRECATED, and you should use context based callbacks. See
+        https://git.io/fxJuV for more info.
+
    Args:
-        callback (:obj:`callable`): A function that takes ``bot, update`` as positional arguments.
-            It will be called when the :attr:`check_update` has determined that an update should be
-            processed by this handler.
+        callback (:obj:`callable`): The callback function for this handler. Will be called when
+            :attr:`check_update` has determined that an update should be processed by this handler.
+            Callback signature for context based API:
+
+            ``def callback(update: Update, context: CallbackContext)``
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
        pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
+            DEPRECATED: Please switch to context based callbacks.
            instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
            that contains new updates which can be used to insert updates. Default is ``False``.
        pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``job_queue`` will be passed to the callback function. It will be a
            :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
            which can be used to schedule new jobs. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``user_data`` will be passed to the callback function. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``chat_data`` will be passed to the callback function. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.

    """

-    def __init__(self,
-                 callback,
-                 pass_update_queue=False,
-                 pass_job_queue=False,
-                 pass_user_data=False,
-                 pass_chat_data=False):
-        super(PreCheckoutQueryHandler, self).__init__(
-            callback,
-            pass_update_queue=pass_update_queue,
-            pass_job_queue=pass_job_queue,
-            pass_user_data=pass_user_data,
-            pass_chat_data=pass_chat_data)
-
    def check_update(self, update):
        """Determines whether an update should be passed to this handlers :attr:`callback`.

@@ -85,14 +84,3 @@ class PreCheckoutQueryHandler(Handler):

        """
        return isinstance(update, Update) and update.pre_checkout_query
-
-    def handle_update(self, update, dispatcher):
-        """Send the update to the :attr:`callback`.
-
-        Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
-            dispatcher (:class:`telegram.ext.Dispatcher`): Dispatcher that originated the Update.
-
-        """
-        optional_args = self.collect_optional_args(dispatcher, update)
-        return self.callback(dispatcher.bot, update, **optional_args)
@@ -19,16 +19,14 @@
 # TODO: Remove allow_edited
 """This module contains the RegexHandler class."""

-import re
 import warnings

-from future.utils import string_types
+from telegram.utils.deprecate import TelegramDeprecationWarning

-from telegram import Update
-from .handler import Handler
+from telegram.ext import MessageHandler, Filters


-class RegexHandler(Handler):
+class RegexHandler(MessageHandler):
    """Handler class to handle Telegram updates based on a regex.

    It uses a regular expression to check text messages. Read the documentation of the ``re``
@@ -38,30 +36,34 @@ class RegexHandler(Handler):
    Attributes:
        pattern (:obj:`str` | :obj:`Pattern`): The regex pattern.
        callback (:obj:`callable`): The callback function for this handler.
-        pass_groups (:obj:`bool`): Optional. Determines whether ``groups`` will be passed to the
+        pass_groups (:obj:`bool`): Determines whether ``groups`` will be passed to the
            callback function.
-        pass_groupdict (:obj:`bool`): Optional. Determines whether ``groupdict``. will be passed to
+        pass_groupdict (:obj:`bool`): Determines whether ``groupdict``. will be passed to
            the callback function.
-        pass_update_queue (:obj:`bool`): Optional. Determines whether ``update_queue`` will be
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Optional. Determines whether ``job_queue`` will be passed to
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
            the callback function.
-        pass_user_data (:obj:`bool`): Optional. Determines whether ``user_data`` will be passed to
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
            the callback function.
-        pass_chat_data (:obj:`bool`): Optional. Determines whether ``chat_data`` will be passed to
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
            the callback function.

    Note:
-        :attr:`pass_user_data` and :attr:`pass_chat_data` determine whether a ``dict`` you
-        can use to keep any data in will be sent to the :attr:`callback` function. Related to
-        either the user or the chat that the update was sent in. For each update from the same user
-        or in the same chat, it will be the same ``dict``.
+        This handler is being deprecated. For the same usecase use:
+        ``MessageHandler(Filters.regex(r'pattern'), callback)``
+

    Args:
        pattern (:obj:`str` | :obj:`Pattern`): The regex pattern.
-        callback (:obj:`callable`): A function that takes ``bot, update`` as positional arguments.
-            It will be called when the :attr:`check_update` has determined that an update should be
-            processed by this handler.
+        callback (:obj:`callable`): The callback function for this handler. Will be called when
+            :attr:`check_update` has determined that an update should be processed by this handler.
+            Callback signature for context based API:
+
+            ``def callback(update: Update, context: CallbackContext)``
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
        pass_groups (:obj:`bool`, optional): If the callback should be passed the result of
            ``re.match(pattern, data).groups()`` as a keyword argument called ``groups``.
            Default is ``False``
@@ -86,8 +88,6 @@ class RegexHandler(Handler):
            Default is ``True``.
        edited_updates (:obj:`bool`, optional): Should "edited" message updates be handled? Default
            is ``False``.
-        allow_edited (:obj:`bool`, optional): If the handler should also accept edited messages.
-            Default is ``False`` - Deprecated. use edited_updates instead.

    Raises:
        ValueError
@@ -106,68 +106,27 @@ class RegexHandler(Handler):
                 allow_edited=False,
                 message_updates=True,
                 channel_post_updates=False,
-                 edited_updates=False
-                 ):
-        if not message_updates and not channel_post_updates and not edited_updates:
-            raise ValueError(
-                'message_updates, channel_post_updates and edited_updates are all False')
-        if allow_edited:
-            warnings.warn('allow_edited is getting deprecated, please use edited_updates instead')
-            edited_updates = allow_edited
-
-        super(RegexHandler, self).__init__(
-            callback,
-            pass_update_queue=pass_update_queue,
-            pass_job_queue=pass_job_queue,
-            pass_user_data=pass_user_data,
-            pass_chat_data=pass_chat_data)
-
-        if isinstance(pattern, string_types):
-            pattern = re.compile(pattern)
-
-        self.pattern = pattern
+                 edited_updates=False):
+        warnings.warn('RegexHandler is deprecated. See https://git.io/fxJuV for more info',
+                      TelegramDeprecationWarning,
+                      stacklevel=2)
+        super(RegexHandler, self).__init__(Filters.regex(pattern),
+                                           callback,
+                                           pass_update_queue=pass_update_queue,
+                                           pass_job_queue=pass_job_queue,
+                                           pass_user_data=pass_user_data,
+                                           pass_chat_data=pass_chat_data,
+                                           message_updates=message_updates,
+                                           channel_post_updates=channel_post_updates,
+                                           edited_updates=edited_updates)
        self.pass_groups = pass_groups
        self.pass_groupdict = pass_groupdict
-        self.allow_edited = allow_edited
-        self.message_updates = message_updates
-        self.channel_post_updates = channel_post_updates
-        self.edited_updates = edited_updates
-
-    def check_update(self, update):
-        """Determines whether an update should be passed to this handlers :attr:`callback`.
-
-        Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
-
-        Returns:
-            :obj:`bool`
-
-        """
-        if not isinstance(update, Update) and not update.effective_message:
-            return False
-        if any([self.message_updates and update.message,
-                self.edited_updates and (update.edited_message or update.edited_channel_post),
-                self.channel_post_updates and update.channel_post]) and \
-                update.effective_message.text:
-            match = re.match(self.pattern, update.effective_message.text)
-            return bool(match)
-        return False
-
-    def handle_update(self, update, dispatcher):
-        """Send the update to the :attr:`callback`.
-
-        Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
-            dispatcher (:class:`telegram.ext.Dispatcher`): Dispatcher that originated the Update.
-
-        """
-
-        optional_args = self.collect_optional_args(dispatcher, update)
-        match = re.match(self.pattern, update.effective_message.text)

+    def collect_optional_args(self, dispatcher, update=None, check_result=None):
+        optional_args = super(RegexHandler, self).collect_optional_args(dispatcher, update,
+                                                                        check_result)
        if self.pass_groups:
-            optional_args['groups'] = match.groups()
+            optional_args['groups'] = check_result['matches'][0].groups()
        if self.pass_groupdict:
-            optional_args['groupdict'] = match.groupdict()
-
-        return self.callback(dispatcher.bot, update, **optional_args)
+            optional_args['groupdict'] = check_result['matches'][0].groupdict()
+        return optional_args
@@ -27,13 +27,13 @@ class ShippingQueryHandler(Handler):

    Attributes:
        callback (:obj:`callable`): The callback function for this handler.
-        pass_update_queue (:obj:`bool`): Optional. Determines whether ``update_queue`` will be
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Optional. Determines whether ``job_queue`` will be passed to
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
            the callback function.
-        pass_user_data (:obj:`bool`): Optional. Determines whether ``user_data`` will be passed to
+        pass_user_data (:obj:`bool`): Determines whether ``user_data`` will be passed to
            the callback function.
-        pass_chat_data (:obj:`bool`): Optional. Determines whether ``chat_data`` will be passed to
+        pass_chat_data (:obj:`bool`): Determines whether ``chat_data`` will be passed to
            the callback function.

    Note:
@@ -42,38 +42,37 @@ class ShippingQueryHandler(Handler):
        either the user or the chat that the update was sent in. For each update from the same user
        or in the same chat, it will be the same ``dict``.

+        Note that this is DEPRECATED, and you should use context based callbacks. See
+        https://git.io/fxJuV for more info.
+
    Args:
-        callback (:obj:`callable`): A function that takes ``bot, update`` as positional arguments.
-            It will be called when the :attr:`check_update` has determined that an update should be
-            processed by this handler.
+        callback (:obj:`callable`): The callback function for this handler. Will be called when
+            :attr:`check_update` has determined that an update should be processed by this handler.
+            Callback signature for context based API:
+
+            ``def callback(update: Update, context: CallbackContext)``
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
        pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
            instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
            that contains new updates which can be used to insert updates. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``job_queue`` will be passed to the callback function. It will be a
            :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
            which can be used to schedule new jobs. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_user_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``user_data`` will be passed to the callback function. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_chat_data (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``chat_data`` will be passed to the callback function. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.

    """

-    def __init__(self,
-                 callback,
-                 pass_update_queue=False,
-                 pass_job_queue=False,
-                 pass_user_data=False,
-                 pass_chat_data=False):
-        super(ShippingQueryHandler, self).__init__(
-            callback,
-            pass_update_queue=pass_update_queue,
-            pass_job_queue=pass_job_queue,
-            pass_user_data=pass_user_data,
-            pass_chat_data=pass_chat_data)
-
    def check_update(self, update):
        """Determines whether an update should be passed to this handlers :attr:`callback`.

@@ -85,14 +84,3 @@ class ShippingQueryHandler(Handler):

        """
        return isinstance(update, Update) and update.shipping_query
-
-    def handle_update(self, update, dispatcher):
-        """Send the update to the :attr:`callback`.
-
-        Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
-            dispatcher (:class:`telegram.ext.Dispatcher`): Dispatcher that originated the Update.
-
-        """
-        optional_args = self.collect_optional_args(dispatcher, update)
-        return self.callback(dispatcher.bot, update, **optional_args)
@@ -33,31 +33,37 @@ class StringCommandHandler(Handler):
    Attributes:
        command (:obj:`str`): The command this handler should listen for.
        callback (:obj:`callable`): The callback function for this handler.
-        pass_args (:obj:`bool`): Optional. Determines whether the handler should be passed
+        pass_args (:obj:`bool`): Determines whether the handler should be passed
            ``args``.
-        pass_update_queue (:obj:`bool`): Optional. Determines whether ``update_queue`` will be
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Optional. Determines whether ``job_queue`` will be passed to
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
            the callback function.

-
    Args:
-        command (:obj:`str`): The command this handler should listen for.
-        callback (:obj:`callable`): A function that takes ``bot, update`` as positional arguments.
-            It will be called when the :attr:`check_update` has determined that a command should be
-            processed by this handler.
+        callback (:obj:`callable`): The callback function for this handler. Will be called when
+            :attr:`check_update` has determined that an update should be processed by this handler.
+            Callback signature for context based API:
+
+            ``def callback(update: Update, context: CallbackContext)``
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
        pass_args (:obj:`bool`, optional): Determines whether the handler should be passed the
            arguments passed to the command as a keyword argument called ``args``. It will contain
            a list of strings, which is the text following the command split on single or
            consecutive whitespace characters. Default is ``False``
+            DEPRECATED: Please switch to context based callbacks.
        pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
            instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
            that contains new updates which can be used to insert updates. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``job_queue`` will be passed to the callback function. It will be a
            class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
            which can be used to schedule new jobs. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.

    """

@@ -68,7 +74,9 @@ class StringCommandHandler(Handler):
                 pass_update_queue=False,
                 pass_job_queue=False):
        super(StringCommandHandler, self).__init__(
-            callback, pass_update_queue=pass_update_queue, pass_job_queue=pass_job_queue)
+            callback,
+            pass_update_queue=pass_update_queue,
+            pass_job_queue=pass_job_queue)
        self.command = command
        self.pass_args = pass_args

@@ -76,28 +84,24 @@ class StringCommandHandler(Handler):
        """Determines whether an update should be passed to this handlers :attr:`callback`.

        Args:
-            update (:obj:`str`): An incomming command.
+            update (:obj:`str`): An incoming command.

        Returns:
            :obj:`bool`

        """
+        if isinstance(update, string_types) and update.startswith('/'):
+            args = update[1:].split(' ')
+            if args[0] == self.command:
+                return args[1:]

-        return (isinstance(update, string_types) and update.startswith('/')
-                and update[1:].split(' ')[0] == self.command)
-
-    def handle_update(self, update, dispatcher):
-        """Send the update to the :attr:`callback`.
-
-        Args:
-            update (:obj:`str`): An incomming command.
-            dispatcher (:class:`telegram.ext.Dispatcher`): Dispatcher that originated the command.
-
-        """
-
-        optional_args = self.collect_optional_args(dispatcher)
-
+    def collect_optional_args(self, dispatcher, update=None, check_result=None):
+        optional_args = super(StringCommandHandler, self).collect_optional_args(dispatcher,
+                                                                                update,
+                                                                                check_result)
        if self.pass_args:
-            optional_args['args'] = update.split()[1:]
+            optional_args['args'] = check_result
+        return optional_args

-        return self.callback(dispatcher.bot, update, **optional_args)
+    def collect_additional_context(self, context, update, dispatcher, check_result):
+        context.args = check_result
@@ -38,34 +38,43 @@ class StringRegexHandler(Handler):
    Attributes:
        pattern (:obj:`str` | :obj:`Pattern`): The regex pattern.
        callback (:obj:`callable`): The callback function for this handler.
-        pass_groups (:obj:`bool`): Optional. Determines whether ``groups`` will be passed to the
+        pass_groups (:obj:`bool`): Determines whether ``groups`` will be passed to the
            callback function.
-        pass_groupdict (:obj:`bool`): Optional. Determines whether ``groupdict``. will be passed to
+        pass_groupdict (:obj:`bool`): Determines whether ``groupdict``. will be passed to
            the callback function.
-        pass_update_queue (:obj:`bool`): Optional. Determines whether ``update_queue`` will be
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Optional. Determines whether ``job_queue`` will be passed to
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
            the callback function.

    Args:
        pattern (:obj:`str` | :obj:`Pattern`): The regex pattern.
-        callback (:obj:`callable`): A function that takes ``bot, update`` as positional arguments.
-            It will be called when the :attr:`check_update` has determined that an update should be
-            processed by this handler.
+        callback (:obj:`callable`): The callback function for this handler. Will be called when
+            :attr:`check_update` has determined that an update should be processed by this handler.
+            Callback signature for context based API:
+
+            ``def callback(update: Update, context: CallbackContext)``
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
        pass_groups (:obj:`bool`, optional): If the callback should be passed the result of
            ``re.match(pattern, data).groups()`` as a keyword argument called ``groups``.
            Default is ``False``
+            DEPRECATED: Please switch to context based callbacks.
        pass_groupdict (:obj:`bool`, optional): If the callback should be passed the result of
            ``re.match(pattern, data).groupdict()`` as a keyword argument called ``groupdict``.
            Default is ``False``
+            DEPRECATED: Please switch to context based callbacks.
        pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
            instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
            that contains new updates which can be used to insert updates. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``job_queue`` will be passed to the callback function. It will be a
            :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
            which can be used to schedule new jobs. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.

    """

@@ -77,7 +86,9 @@ class StringRegexHandler(Handler):
                 pass_update_queue=False,
                 pass_job_queue=False):
        super(StringRegexHandler, self).__init__(
-            callback, pass_update_queue=pass_update_queue, pass_job_queue=pass_job_queue)
+            callback,
+            pass_update_queue=pass_update_queue,
+            pass_job_queue=pass_job_queue)

        if isinstance(pattern, string_types):
            pattern = re.compile(pattern)
@@ -90,28 +101,27 @@ class StringRegexHandler(Handler):
        """Determines whether an update should be passed to this handlers :attr:`callback`.

        Args:
-            update (:obj:`str`): An incomming command.
+            update (:obj:`str`): An incoming command.

        Returns:
            :obj:`bool`

        """
-        return isinstance(update, string_types) and bool(re.match(self.pattern, update))
+        if isinstance(update, string_types):
+            match = re.match(self.pattern, update)
+            if match:
+                return match

-    def handle_update(self, update, dispatcher):
-        """Send the update to the :attr:`callback`.
+    def collect_optional_args(self, dispatcher, update=None, check_result=None):
+        optional_args = super(StringRegexHandler, self).collect_optional_args(dispatcher,
+                                                                              update, check_result)
+        if self.pattern:
+            if self.pass_groups:
+                optional_args['groups'] = check_result.groups()
+            if self.pass_groupdict:
+                optional_args['groupdict'] = check_result.groupdict()
+        return optional_args

-        Args:
-            update (:obj:`str`): An incomming command.
-            dispatcher (:class:`telegram.ext.Dispatcher`): Dispatcher that originated the command.
-
-        """
-        optional_args = self.collect_optional_args(dispatcher)
-        match = re.match(self.pattern, update)
-
-        if self.pass_groups:
-            optional_args['groups'] = match.groups()
-        if self.pass_groupdict:
-            optional_args['groupdict'] = match.groupdict()
-
-        return self.callback(dispatcher.bot, update, **optional_args)
+    def collect_additional_context(self, context, update, dispatcher, check_result):
+        if self.pattern:
+            context.matches = [check_result]
@@ -27,36 +27,48 @@ class TypeHandler(Handler):
    Attributes:
        type (:obj:`type`): The ``type`` of updates this handler should process.
        callback (:obj:`callable`): The callback function for this handler.
-        strict (:obj:`bool`): Optional. Use ``type`` instead of ``isinstance``.
-            Default is ``False``
-        pass_update_queue (:obj:`bool`): Optional. Determines whether ``update_queue`` will be
+        strict (:obj:`bool`): Use ``type`` instead of ``isinstance``. Default is ``False``.
+        pass_update_queue (:obj:`bool`): Determines whether ``update_queue`` will be
            passed to the callback function.
-        pass_job_queue (:obj:`bool`): Optional. Determines whether ``job_queue`` will be passed to
+        pass_job_queue (:obj:`bool`): Determines whether ``job_queue`` will be passed to
            the callback function.

    Args:
        type (:obj:`type`): The ``type`` of updates this handler should process, as
            determined by ``isinstance``
-        callback (:obj:`callable`): A function that takes ``bot, update`` as positional arguments.
-            It will be called when the :attr:`check_update` has determined that an update should be
-            processed by this handler.
+        callback (:obj:`callable`): The callback function for this handler. Will be called when
+            :attr:`check_update` has determined that an update should be processed by this handler.
+            Callback signature for context based API:
+
+            ``def callback(update: Update, context: CallbackContext)``
+
+            The return value of the callback is usually ignored except for the special case of
+            :class:`telegram.ext.ConversationHandler`.
        strict (:obj:`bool`, optional): Use ``type`` instead of ``isinstance``.
            Default is ``False``
        pass_update_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
            instance used by the :class:`telegram.ext.Updater` and :class:`telegram.ext.Dispatcher`
            that contains new updates which can be used to insert updates. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.
        pass_job_queue (:obj:`bool`, optional): If set to ``True``, a keyword argument called
            ``job_queue`` will be passed to the callback function. It will be a
            :class:`telegram.ext.JobQueue` instance created by the :class:`telegram.ext.Updater`
            which can be used to schedule new jobs. Default is ``False``.
+            DEPRECATED: Please switch to context based callbacks.

    """

-    def __init__(self, type, callback, strict=False, pass_update_queue=False,
+    def __init__(self,
+                 type,
+                 callback,
+                 strict=False,
+                 pass_update_queue=False,
                 pass_job_queue=False):
        super(TypeHandler, self).__init__(
-            callback, pass_update_queue=pass_update_queue, pass_job_queue=pass_job_queue)
+            callback,
+            pass_update_queue=pass_update_queue,
+            pass_job_queue=pass_job_queue)
        self.type = type
        self.strict = strict

@@ -70,20 +82,7 @@ class TypeHandler(Handler):
            :obj:`bool`

        """
-
        if not self.strict:
            return isinstance(update, self.type)
        else:
            return type(update) is self.type
-
-    def handle_update(self, update, dispatcher):
-        """Send the update to the :attr:`callback`.
-
-        Args:
-            update (:class:`telegram.Update`): Incoming telegram update.
-            dispatcher (:class:`telegram.ext.Dispatcher`): Dispatcher that originated the Update.
-
-        """
-        optional_args = self.collect_optional_args(dispatcher)
-
-        return self.callback(dispatcher.bot, update, **optional_args)
@@ -19,11 +19,9 @@
 """This module contains the class Updater, which tries to make creating Telegram bots intuitive."""

 import logging
-import os
 import ssl
 from threading import Thread, Lock, current_thread, Event
 from time import sleep
-import subprocess
 from signal import signal, SIGINT, SIGTERM, SIGABRT
 from queue import Queue

@@ -32,7 +30,7 @@ from telegram.ext import Dispatcher, JobQueue
 from telegram.error import Unauthorized, InvalidToken, RetryAfter, TimedOut
 from telegram.utils.helpers import get_signal_name
 from telegram.utils.request import Request
-from telegram.utils.webhookhandler import (WebhookServer, WebhookHandler)
+from telegram.utils.webhookhandler import (WebhookServer, WebhookAppClass)

 logging.getLogger(__name__).addHandler(logging.NullHandler())

@@ -57,6 +55,9 @@ class Updater(object):
        dispatcher (:class:`telegram.ext.Dispatcher`): Dispatcher that handles the updates and
            dispatches them to the handlers.
        running (:obj:`bool`): Indicates if the updater is running.
+        persistence (:class:`telegram.ext.BasePersistence`): Optional. The persistence class to
+            store data that should be persistent over restarts.
+        use_context (:obj:`bool`, optional): ``True`` if using context based callbacks.

    Args:
        token (:obj:`str`, optional): The bot's token given by the @BotFather.
@@ -75,6 +76,11 @@ class Updater(object):
            `telegram.utils.request.Request` object (ignored if `bot` argument is used). The
            request_kwargs are very useful for the advanced users who would like to control the
            default timeouts and/or control the proxy used for http communication.
+        use_context (:obj:`bool`, optional): If set to ``True`` Use the context based callback API.
+            During the deprecation period of the old API the default is ``False``. **New users**:
+            set this to ``True``.
+        persistence (:class:`telegram.ext.BasePersistence`, optional): The persistence class to
+            store data that should be persistent over restarts.

    Note:
        You must supply either a :attr:`bot` or a :attr:`token` argument.
@@ -94,7 +100,9 @@ class Updater(object):
                 private_key=None,
                 private_key_password=None,
                 user_sig_handler=None,
-                 request_kwargs=None):
+                 request_kwargs=None,
+                 persistence=None,
+                 use_context=False):

        if (token is None) and (bot is None):
            raise ValueError('`token` or `bot` must be passed')
@@ -129,14 +137,18 @@ class Updater(object):
                           private_key_password=private_key_password)
        self.user_sig_handler = user_sig_handler
        self.update_queue = Queue()
-        self.job_queue = JobQueue(self.bot)
+        self.job_queue = JobQueue()
        self.__exception_event = Event()
+        self.persistence = persistence
        self.dispatcher = Dispatcher(
            self.bot,
            self.update_queue,
            job_queue=self.job_queue,
            workers=workers,
-            exception_event=self.__exception_event)
+            exception_event=self.__exception_event,
+            persistence=persistence,
+            use_context=use_context)
+        self.job_queue.set_dispatcher(self.dispatcher)
        self.last_update_id = 0
        self.running = False
        self.is_idle = False
@@ -145,7 +157,8 @@ class Updater(object):
        self.__threads = []

    def _init_thread(self, target, name, *args, **kwargs):
-        thr = Thread(target=self._thread_wrapper, name=name, args=(target,) + args, kwargs=kwargs)
+        thr = Thread(target=self._thread_wrapper, name="Bot:{}:{}".format(self.bot.id, name),
+                     args=(target,) + args, kwargs=kwargs)
        thr.start()
        self.__threads.append(thr)

@@ -356,13 +369,24 @@ class Updater(object):
        if not url_path.startswith('/'):
            url_path = '/{0}'.format(url_path)

+        # Create Tornado app instance
+        app = WebhookAppClass(url_path, self.bot, self.update_queue)
+
+        # Form SSL Context
+        # An SSLError is raised if the private key does not match with the certificate
+        if use_ssl:
+            try:
+                ssl_ctx = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
+                ssl_ctx.load_cert_chain(cert, key)
+            except ssl.SSLError:
+                raise TelegramError('Invalid SSL Certificate')
+        else:
+            ssl_ctx = None
+
        # Create and start server
-        self.httpd = WebhookServer((listen, port), WebhookHandler, self.update_queue, url_path,
-                                   self.bot)
+        self.httpd = WebhookServer(listen, port, app, ssl_ctx)

        if use_ssl:
-            self._check_ssl_cert(cert, key)
-
            # DO NOT CHANGE: Only set webhook if SSL is handled by library
            if not webhook_url:
                webhook_url = self._gen_webhook_url(listen, port, url_path)
@@ -377,26 +401,7 @@ class Updater(object):
            self.logger.warning("cleaning updates is not supported if "
                                "SSL-termination happens elsewhere; skipping")

-        self.httpd.serve_forever(poll_interval=1)
-
-    def _check_ssl_cert(self, cert, key):
-        # Check SSL-Certificate with openssl, if possible
-        try:
-            exit_code = subprocess.call(
-                ["openssl", "x509", "-text", "-noout", "-in", cert],
-                stdout=open(os.devnull, 'wb'),
-                stderr=subprocess.STDOUT)
-        except OSError:
-            exit_code = 0
-        if exit_code == 0:
-            try:
-                self.httpd.socket = ssl.wrap_socket(
-                    self.httpd.socket, certfile=cert, keyfile=key, server_side=True)
-            except ssl.SSLError as error:
-                self.logger.exception('Failed to init SSL socket')
-                raise TelegramError(str(error))
-        else:
-            raise TelegramError('SSL Certificate invalid')
+        self.httpd.serve_forever()

    @staticmethod
    def _gen_webhook_url(listen, port, url_path):
@@ -495,6 +500,10 @@ class Updater(object):
        if self.running:
            self.logger.info('Received signal {} ({}), stopping...'.format(
                signum, get_signal_name(signum)))
+            if self.persistence:
+                # Update user_data and chat_data before flushing
+                self.dispatcher.update_persistence()
+                self.persistence.flush()
            self.stop()
            if self.user_sig_handler:
                self.user_sig_handler(signum, frame)
@@ -22,7 +22,6 @@
 import imghdr
 import mimetypes
 import os
-import sys
 from uuid import uuid4

 from telegram import TelegramError
@@ -56,9 +55,9 @@ class InputFile(object):

        if filename:
            self.filename = filename
-        elif (hasattr(obj, 'name') and
-              not isinstance(obj.name, int) and  # py3
-              obj.name != '<fdopen>'):  # py2
+        elif (hasattr(obj, 'name')
+              and not isinstance(obj.name, int)  # py3
+              and obj.name != '<fdopen>'):  # py2
            # on py2.7, pylint fails to understand this properly
            # pylint: disable=E1101
            self.filename = os.path.basename(obj.name)
@@ -71,13 +70,9 @@ class InputFile(object):
                    self.filename)[0] or DEFAULT_MIME_TYPE
            else:
                self.mimetype = DEFAULT_MIME_TYPE
-        if not self.filename or '.' not in self.filename:
+        if not self.filename:
            self.filename = self.mimetype.replace('/', '.')

-        if sys.version_info < (3,):
-            if isinstance(self.filename, unicode):  # flake8: noqa  pylint: disable=E0602
-                self.filename = self.filename.encode('utf-8', 'replace')
-
    @property
    def field_tuple(self):
        return self.filename, self.input_file_content, self.mimetype
@@ -37,14 +37,16 @@ class InputMediaAnimation(InputMedia):

    Attributes:
        type (:obj:`str`): ``animation``.
-        media (:obj:`str`): File to send. Pass a file_id to send a file that exists on the Telegram
-            servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet.
+        media (:obj:`str` | `filelike object` | :class:`telegram.Animation`): Animation to
+            send. Pass a file_id as String to send an animation that exists on the Telegram
+            servers (recommended), pass an HTTP URL as a String for Telegram to get an
+            animation from the Internet, or upload a new animation using multipart/form-data.
            Lastly you can pass an existing :class:`telegram.Animation` object to send.
        thumb (`filelike object`): Optional. Thumbnail of the
            file sent. The thumbnail should be in JPEG format and less than 200 kB in size.
            A thumbnail's width and height should not exceed 90. Ignored if the file is not
            is passed as a string or file_id.
-        caption (:obj:`str`): Optional. Caption of the animation to be sent, 0-200 characters.
+        caption (:obj:`str`): Optional. Caption of the animation to be sent, 0-1024 characters.
        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.
@@ -61,7 +63,7 @@ class InputMediaAnimation(InputMedia):
            file sent. The thumbnail should be in JPEG format and less than 200 kB in size.
            A thumbnail's width and height should not exceed 90. Ignored if the file is not
            is passed as a string or file_id.
-        caption (:obj:`str`, optional): Caption of the animation to be sent, 0-200 characters.
+        caption (:obj:`str`, optional): Caption of the animation to be sent, 0-1024 characters.
        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.
@@ -111,10 +113,12 @@ class InputMediaPhoto(InputMedia):

    Attributes:
        type (:obj:`str`): ``photo``.
-        media (:obj:`str`): File to send. Pass a file_id to send a file that exists on the
-            Telegram servers (recommended), pass an HTTP URL for Telegram to get a file from the
-            Internet. Lastly you can pass an existing :class:`telegram.PhotoSize` object to send.
-        caption (:obj:`str`): Optional. Caption of the photo to be sent, 0-200 characters.
+        media (:obj:`str` | `filelike object` | :class:`telegram.PhotoSize`): Photo to send.
+            Pass a file_id as String to send a photo that exists on the Telegram servers
+            (recommended), pass an HTTP URL as a String for Telegram to get a photo from the
+            Internet, or upload a new photo using multipart/form-data. Lastly you can pass
+            an existing :class:`telegram.PhotoSize` object to send.
+        caption (:obj:`str`): Optional. Caption of the photo to be sent, 0-1024 characters.
        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.
@@ -123,7 +127,7 @@ class InputMediaPhoto(InputMedia):
        media (:obj:`str`): File to send. Pass a file_id to send a file that exists on the
            Telegram servers (recommended), pass an HTTP URL for Telegram to get a file from the
            Internet. Lastly you can pass an existing :class:`telegram.PhotoSize` object to send.
-        caption (:obj:`str`, optional ): Caption of the photo to be sent, 0-200 characters.
+        caption (:obj:`str`, optional ): Caption of the photo to be sent, 0-1024 characters.
        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.
@@ -150,10 +154,12 @@ class InputMediaVideo(InputMedia):

    Attributes:
        type (:obj:`str`): ``video``.
-        media (:obj:`str`): File to send. Pass a file_id to send a file that exists on the Telegram
-            servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet.
-            Lastly you can pass an existing :class:`telegram.Video` object to send.
-        caption (:obj:`str`): Optional. Caption of the video to be sent, 0-200 characters.
+        media (:obj:`str` | `filelike object` | :class:`telegram.Video`): Video file to send.
+            Pass a file_id as String to send an video file that exists on the Telegram servers
+            (recommended), pass an HTTP URL as a String for Telegram to get an video file from
+            the Internet, or upload a new one using multipart/form-data. Lastly you can pass
+            an existing :class:`telegram.Video` object to send.
+        caption (:obj:`str`): Optional. Caption of the video to be sent, 0-1024 characters.
        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.
@@ -171,7 +177,7 @@ class InputMediaVideo(InputMedia):
        media (:obj:`str`): File to send. Pass a file_id to send a file that exists on the Telegram
            servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet.
            Lastly you can pass an existing :class:`telegram.Video` object to send.
-        caption (:obj:`str`, optional): Caption of the video to be sent, 0-200 characters.
+        caption (:obj:`str`, optional): Caption of the video to be sent, 0-1024 characters.
        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.
@@ -229,10 +235,12 @@ class InputMediaAudio(InputMedia):

    Attributes:
        type (:obj:`str`): ``audio``.
-        media (:obj:`str`): File to send. Pass a file_id to send a file that exists on the Telegram
-            servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet.
-            Lastly you can pass an existing :class:`telegram.Audio` object to send.
-        caption (:obj:`str`): Optional. Caption of the audio to be sent, 0-200 characters.
+        media (:obj:`str` | `filelike object` | :class:`telegram.Audio`): Audio file to send.
+            Pass a file_id as String to send an audio file that exists on the Telegram servers
+            (recommended), pass an HTTP URL as a String for Telegram to get an audio file from
+            the Internet, or upload a new one using multipart/form-data. Lastly you can pass
+            an existing :class:`telegram.Audio` object to send.
+        caption (:obj:`str`): Optional. Caption of the audio to be sent, 0-1024 characters.
        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.
@@ -249,7 +257,7 @@ class InputMediaAudio(InputMedia):
        media (:obj:`str`): File to send. Pass a file_id to send a file that exists on the Telegram
            servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet.
            Lastly you can pass an existing :class:`telegram.Document` object to send.
-        caption (:obj:`str`, optional): Caption of the audio to be sent, 0-200 characters.
+        caption (:obj:`str`, optional): Caption of the audio to be sent, 0-1024 characters.
        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.
@@ -304,10 +312,12 @@ class InputMediaDocument(InputMedia):

    Attributes:
        type (:obj:`str`): ``document``.
-        media (:obj:`str`): File to send. Pass a file_id to send a file that exists on the Telegram
-            servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet.
-            Lastly you can pass an existing :class:`telegram.Document` object to send.
-        caption (:obj:`str`): Optional. Caption of the document to be sent, 0-200 characters.
+        media (:obj:`str` | `filelike object` | :class:`telegram.Document`): File to send.
+            Pass a file_id as String to send a file that exists on the Telegram servers
+            (recommended), pass an HTTP URL as a String for Telegram to get a file from the
+            Internet, or upload a new one using multipart/form-data. Lastly you can pass
+            an existing :class:`telegram.Document` object to send.
+        caption (:obj:`str`): Optional. Caption of the document to be sent, 0-1024 characters.
        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.
@@ -320,7 +330,7 @@ class InputMediaDocument(InputMedia):
        media (:obj:`str`): File to send. Pass a file_id to send a file that exists on the Telegram
            servers (recommended), pass an HTTP URL for Telegram to get a file from the Internet.
            Lastly you can pass an existing :class:`telegram.Document` object to send.
-        caption (:obj:`str`, optional): Caption of the document to be sent, 0-200 characters.
+        caption (:obj:`str`, optional): Caption of the document to be sent, 0-1024 characters.
        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.
@@ -31,8 +31,10 @@ 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.
+        login_url (:class:`telegram.LoginUrl`) Optional. An HTTP URL used to automatically
+            authorize the user.
        callback_data (:obj:`str`): Optional. Data to be sent in a callback query to the bot when
-            button is pressed, 1-64 bytes.
+            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.
@@ -45,8 +47,10 @@ class InlineKeyboardButton(TelegramObject):
    Args:
        text (:obj:`str`): Label text on the button.
        url (:obj:`str`): HTTP url to be opened when button is pressed.
+        login_url (:class:`telegram.LoginUrl`, optional) An HTTP URL used to automatically
+            authorize the user.
        callback_data (:obj:`str`, optional): Data to be sent in a callback query to the bot when
-            button is pressed, 1-64 bytes.
+            button is pressed, 1-64 UTF-8 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
@@ -76,14 +80,30 @@ class InlineKeyboardButton(TelegramObject):
                 switch_inline_query_current_chat=None,
                 callback_game=None,
                 pay=None,
+                 login_url=None,
                 **kwargs):
        # Required
        self.text = text

        # Optionals
-        self.url = url
-        self.callback_data = callback_data
-        self.switch_inline_query = switch_inline_query
-        self.switch_inline_query_current_chat = switch_inline_query_current_chat
-        self.callback_game = callback_game
-        self.pay = pay
+        if url:
+            self.url = url
+        if login_url:
+            self.login_url = login_url
+        if callback_data:
+            self.callback_data = callback_data
+        if switch_inline_query:
+            self.switch_inline_query = switch_inline_query
+        if switch_inline_query_current_chat:
+            self.switch_inline_query_current_chat = switch_inline_query_current_chat
+        if callback_game:
+            self.callback_game = callback_game
+        if pay:
+            self.pay = pay
+
+    @classmethod
+    def de_json(cls, data, bot):
+        if not data:
+            return None
+
+        return cls(**data)
@@ -18,7 +18,7 @@
 # along with this program.  If not, see [http://www.gnu.org/licenses/].
 """This module contains an object that represents a Telegram InlineKeyboardMarkup."""

-from telegram import ReplyMarkup
+from telegram import ReplyMarkup, InlineKeyboardButton


 class InlineKeyboardMarkup(ReplyMarkup):
@@ -48,3 +48,64 @@ class InlineKeyboardMarkup(ReplyMarkup):
            data['inline_keyboard'].append([x.to_dict() for x in inline_keyboard])

        return data
+
+    @classmethod
+    def de_json(cls, data, bot):
+        if not data:
+            return None
+        keyboard = []
+        for row in data['inline_keyboard']:
+            tmp = []
+            for col in row:
+                tmp.append(InlineKeyboardButton.de_json(col, bot))
+            keyboard.append(tmp)
+
+        return cls(keyboard)
+
+    @classmethod
+    def from_button(cls, button, **kwargs):
+        """Shortcut for::
+
+            InlineKeyboardMarkup([[button]], **kwargs)
+
+        Return an InlineKeyboardMarkup from a single InlineKeyboardButton
+
+        Args:
+            button (:class:`telegram.InlineKeyboardButton`): The button to use in the markup
+            **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+
+        """
+        return cls([[button]], **kwargs)
+
+    @classmethod
+    def from_row(cls, button_row, **kwargs):
+        """Shortcut for::
+
+            InlineKeyboardMarkup([button_row], **kwargs)
+
+        Return an InlineKeyboardMarkup from a single row of InlineKeyboardButtons
+
+        Args:
+            button_row (List[:class:`telegram.InlineKeyboardButton`]): The button to use in the
+                markup
+            **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+
+        """
+        return cls([button_row], **kwargs)
+
+    @classmethod
+    def from_column(cls, button_column, **kwargs):
+        """Shortcut for::
+
+            InlineKeyboardMarkup([[button] for button in button_column], **kwargs)
+
+        Return an InlineKeyboardMarkup from a single column of InlineKeyboardButtons
+
+        Args:
+            button_column (List[:class:`telegram.InlineKeyboardButton`]): The button to use in the
+                markup
+            **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+
+        """
+        button_grid = [[button] for button in button_column]
+        return cls(button_grid, **kwargs)
@@ -31,7 +31,7 @@ class InlineQueryResultCachedAudio(InlineQueryResult):
        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-200 characters
+        caption (:obj:`str`): Optional. Caption, 0-1024 characters
        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.
@@ -43,7 +43,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-200 characters
+        caption (:obj:`str`, optional): Caption, 0-1024 characters
        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.
@@ -33,7 +33,7 @@ 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-200 characters
+        caption (:obj:`str`): Optional. Caption, 0-1024 characters
        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 +47,7 @@ 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-200 characters
+        caption (:obj:`str`, optional): Caption, 0-1024 characters
        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.
@@ -33,7 +33,7 @@ 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-200 characters
+        caption (:obj:`str`): Optional. Caption, 0-1024 characters
        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.
@@ -46,7 +46,7 @@ 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-200 characters
+        caption (:obj:`str`, optional): Caption, 0-1024 characters
        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.
@@ -33,7 +33,7 @@ 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-200 characters
+        caption (:obj:`str`): Optional. Caption, 0-1024 characters
        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.
@@ -46,7 +46,7 @@ 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-200 characters
+        caption (:obj:`str`, optional): Caption, 0-1024 characters
        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.
@@ -34,7 +34,7 @@ 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-200 characters
+        caption (:obj:`str`): Optional. Caption, 0-1024 characters
        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 +48,7 @@ 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-200 characters
+        caption (:obj:`str`, optional): Caption, 0-1024 characters
        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.
@@ -34,7 +34,7 @@ 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-200 characters.
+        caption (:obj:`str`): Optional. Caption, 0-1024 characters.
        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 +48,7 @@ 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-200 characters.
+        caption (:obj:`str`, optional): Caption, 0-1024 characters.
        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.
@@ -32,7 +32,7 @@ class InlineQueryResultCachedVoice(InlineQueryResult):
        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
        voice_file_id (:obj:`str`): A valid file identifier for the voice message.
        title (:obj:`str`): Voice message title.
-        caption (:obj:`str`): Optional. Caption, 0-200 characters.
+        caption (:obj:`str`): Optional. Caption, 0-1024 characters.
        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.
@@ -45,7 +45,7 @@ class InlineQueryResultCachedVoice(InlineQueryResult):
        id (:obj:`str`): Unique identifier for this result, 1-64 bytes.
        voice_file_id (:obj:`str`): A valid file identifier for the voice message.
        title (:obj:`str`): Voice message title.
-        caption (:obj:`str`, optional): Caption, 0-200 characters.
+        caption (:obj:`str`, optional): Caption, 0-1024 characters.
        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.
@@ -32,7 +32,7 @@ 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-200 characters
+        caption (:obj:`str`): Optional. Caption, 0-1024 characters
        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.
@@ -51,7 +51,7 @@ 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-200 characters
+        caption (:obj:`str`, optional): Caption, 0-1024 characters
        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.
@@ -36,7 +36,7 @@ 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-200 characters
+        caption (:obj:`str`): Optional. Caption, 0-1024 characters
        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.
@@ -53,7 +53,7 @@ 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 (:obj:`str`, optional): Caption, 0-200 characters
+        caption (:obj:`str`, optional): Caption, 0-1024 characters
        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.
@@ -37,7 +37,7 @@ 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-200 characters
+        caption (:obj:`str`): Optional. Caption, 0-1024 characters
        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.
@@ -54,7 +54,7 @@ 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-200 characters
+        caption (:obj:`str`, optional): Caption, 0-1024 characters
        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.
@@ -37,7 +37,7 @@ 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-200 characters
+        caption (:obj:`str`): Optional. Caption, 0-1024 characters
        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.
@@ -55,7 +55,7 @@ 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-200 characters
+        caption (:obj:`str`, optional): Caption, 0-1024 characters
        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.
@@ -35,7 +35,7 @@ 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-200 characters
+        caption (:obj:`str`): Optional. Caption, 0-1024 characters
        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.
@@ -54,7 +54,7 @@ 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-200 characters.
+        caption (:obj:`str`, optional): Caption, 0-1024 characters.
        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.
@@ -33,7 +33,7 @@ class InlineQueryResultVoice(InlineQueryResult):
        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.
-        caption (:obj:`str`): Optional. Caption, 0-200 characters.
+        caption (:obj:`str`): Optional. Caption, 0-1024 characters.
        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 +47,7 @@ class InlineQueryResultVoice(InlineQueryResult):
        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.
-        caption (:obj:`str`, optional): Caption, 0-200 characters.
+        caption (:obj:`str`, optional): Caption, 0-1024 characters.
        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.
@@ -0,0 +1,65 @@
+#!/usr/bin/env python
+# pylint: disable=R0903
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2019
+# 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 LoginUrl."""
+from telegram import TelegramObject
+
+
+class LoginUrl(TelegramObject):
+    """This object represents a parameter of the inline keyboard button used to automatically
+    authorize a user. Serves as a great replacement for the Telegram Login Widget when the user is
+    coming from Telegram. All the user needs to do is tap/click a button and confirm that they want
+    to log in. Telegram apps support these buttons as of version 5.7.
+    Sample bot: @discussbot
+
+    Attributes:
+        url (:obj:`str`): An HTTP URL to be opened with user authorization data.
+        forward_text (:obj:`str`): Optional. New text of the button in forwarded messages.
+        bot_username (:obj:`str`): Optional. Username of a bot, which will be used for user
+            authorization.
+        request_write_access (:obj:`bool`): Optional. Pass True to request the permission for your
+            bot to send messages to the user.
+
+    Args:
+        url (:obj:`str`): An HTTP URL to be opened with user authorization data added to the query
+            string when the button is pressed. If the user refuses to provide authorization data,
+            the original URL without information about the user will be opened. The data added is
+            the same as described in Receiving authorization data.
+            NOTE: You must always check the hash of the received data to verify the authentication
+            and the integrity of the data as described in Checking authorization.
+        forward_text (:obj:`str`, optional): New text of the button in forwarded messages.
+        bot_username (:obj:`str`, optional): Username of a bot, which will be used for user
+            authorization. See Setting up a bot for more details. If not specified, the current
+            bot's username will be assumed. The url's domain must be the same as the domain linked
+            with the bot. See Linking your domain to the bot for more details.
+        request_write_access (:obj:`bool`, optional): Pass True to request the permission for your
+            bot to send messages to the user.
+    """
+
+    def __init__(self, url, forward_text=None, bot_username=None, request_write_access=None):
+        self.url = url
+
+        if forward_text:
+            self.forward_text = forward_text
+        if bot_username:
+            self.bot_username = bot_username
+        if request_write_access:
+            self.request_write_access = request_write_access
+
+        self._id_attrs = (self.url,)
@@ -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)
+                      SuccessfulPayment, VideoNote, PassportData, Poll, InlineKeyboardMarkup)
 from telegram import ParseMode
 from telegram.utils.helpers import escape_markdown, to_timestamp, from_timestamp

@@ -73,7 +73,8 @@ class Message(TelegramObject):
        video_note (:class:`telegram.VideoNote`): Optional. Information about the video message.
        new_chat_members (List[:class:`telegram.User`]): Optional. Information about new members to
            the chat. (the bot itself may be one of these members).
-        caption (:obj:`str`): Optional. Caption for the document, photo or video, 0-200 characters.
+        caption (:obj:`str`): Optional. Caption for the document, photo or video, 0-1024
+            characters.
        contact (:class:`telegram.Contact`): Optional. Information about the contact.
        location (:class:`telegram.Location`): Optional. Information about the location.
        venue (:class:`telegram.Venue`): Optional. Information about the venue.
@@ -98,9 +99,15 @@ class Message(TelegramObject):
            has logged in.
        forward_signature (:obj:`str`): Optional. Signature of the post author for messages
            forwarded from channels.
+        forward_sender_name	(:obj:`str`): Optional. Sender's name for messages forwarded from users
+            who disallow adding a link to their account in forwarded messages.
        author_signature (:obj:`str`): Optional. Signature of the post author for messages
            in channels.
-        passport_data (:class:`telegram.PassportData`): Optional. Telegram Passport data
+        passport_data (:class:`telegram.PassportData`): Optional. Telegram Passport data.
+        poll (:class:`telegram.Poll`): Optional. Message is a native poll,
+            information about the poll.
+        reply_markup (:class:`telegram.InlineKeyboardMarkup`): Optional. Inline keyboard attached
+            to the message.
        bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.

    Args:
@@ -116,6 +123,8 @@ class Message(TelegramObject):
            channel, information about the original channel.
        forward_from_message_id (:obj:`int`, optional): For forwarded channel posts, identifier of
            the original message in the channel.
+        forward_sender_name	(:obj:`str`, optional): Sender's name for messages forwarded from users
+            who disallow adding a link to their account in forwarded messages.
        forward_date (:class:`datetime.datetime`, optional): For forwarded messages, date the
            original message was sent in Unix time. Converted to :class:`datetime.datetime`.
        reply_to_message (:class:`telegram.Message`, optional): For replies, the original message.
@@ -154,7 +163,8 @@ class Message(TelegramObject):
        new_chat_members (List[:class:`telegram.User`], optional): New members that were added to
            the group or supergroup and information about them (the bot itself may be one of these
            members).
-        caption (:obj:`str`, optional): Caption for the document, photo or video, 0-200 characters.
+        caption (:obj:`str`, optional): Caption for the document, photo or video, 0-1024
+            characters.
        contact (:class:`telegram.Contact`, optional): Message is a shared contact, information
            about the contact.
        location (:class:`telegram.Location`, optional): Message is a shared location, information
@@ -199,7 +209,12 @@ class Message(TelegramObject):
            forwarded from channels.
        author_signature (:obj:`str`, optional): Signature of the post author for messages
            in channels.
-        passport_data (:class:`telegram.PassportData`, optional): Telegram Passport data
+        passport_data (:class:`telegram.PassportData`, optional): Telegram Passport data.
+        poll (:class:`telegram.Poll`, optional): Message is a native poll,
+            information about the poll.
+        reply_markup (:class:`telegram.InlineKeyboardMarkup`, optional): Inline keyboard attached
+            to the message. login_url buttons are represented as ordinary url buttons.
+
    """

    _effective_attachment = _UNDEFINED
@@ -207,10 +222,11 @@ class Message(TelegramObject):
    ATTACHMENT_TYPES = ['audio', 'game', 'animation', 'document', 'photo', 'sticker', 'video',
                        'voice', 'video_note', 'contact', 'location', 'venue', 'invoice',
                        'successful_payment']
-    MESSAGE_TYPES = ['text', 'new_chat_members', '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', 'passport_data'] + ATTACHMENT_TYPES
+    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',
+                     'passport_data'] + ATTACHMENT_TYPES

    def __init__(self,
                 message_id,
@@ -257,6 +273,9 @@ class Message(TelegramObject):
                 connected_website=None,
                 animation=None,
                 passport_data=None,
+                 poll=None,
+                 forward_sender_name=None,
+                 reply_markup=None,
                 bot=None,
                 **kwargs):
        # Required
@@ -301,11 +320,13 @@ class Message(TelegramObject):
        self.successful_payment = successful_payment
        self.connected_website = connected_website
        self.forward_signature = forward_signature
+        self.forward_sender_name = forward_sender_name
        self.author_signature = author_signature
        self.media_group_id = media_group_id
        self.animation = animation
        self.passport_data = passport_data
-
+        self.poll = poll
+        self.reply_markup = reply_markup
        self.bot = bot

        self._id_attrs = (self.message_id,)
@@ -359,6 +380,8 @@ class Message(TelegramObject):
        data['invoice'] = Invoice.de_json(data.get('invoice'), bot)
        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['reply_markup'] = InlineKeyboardMarkup.de_json(data.get('reply_markup'), bot)

        return cls(bot=bot, **data)

@@ -702,6 +725,23 @@ class Message(TelegramObject):
        self._quote(kwargs)
        return self.bot.send_contact(self.chat_id, *args, **kwargs)

+    def reply_poll(self, *args, **kwargs):
+        """Shortcut for::
+
+            bot.send_poll(update.message.chat_id, *args, **kwargs)
+
+        Keyword Args:
+            quote (:obj:`bool`, optional): If set to ``True``, the photo 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_poll(self.chat_id, *args, **kwargs)
+
    def forward(self, chat_id, disable_notification=False):
        """Shortcut for::

@@ -838,7 +878,7 @@ class Message(TelegramObject):
            entity_text = self.text.encode('utf-16-le')
            entity_text = entity_text[entity.offset * 2:(entity.offset + entity.length) * 2]

-        return entity_text.decode('utf-16-le')
+            return entity_text.decode('utf-16-le')

    def parse_caption_entity(self, entity):
        """Returns the text from a given :class:`telegram.MessageEntity`.
@@ -863,7 +903,7 @@ class Message(TelegramObject):
            entity_text = self.caption.encode('utf-16-le')
            entity_text = entity_text[entity.offset * 2:(entity.offset + entity.length) * 2]

-        return entity_text.decode('utf-16-le')
+            return entity_text.decode('utf-16-le')

    def parse_entities(self, types=None):
        """
@@ -943,7 +983,9 @@ class Message(TelegramObject):

            if entity.type == MessageEntity.TEXT_LINK:
                insert = '<a href="{}">{}</a>'.format(entity.url, text)
-            elif (entity.type == MessageEntity.URL) and urled:
+            elif entity.type == MessageEntity.TEXT_MENTION and entity.user:
+                insert = '<a href="tg://user?id={}">{}</a>'.format(entity.user.id, text)
+            elif entity.type == MessageEntity.URL and urled:
                insert = '<a href="{0}">{0}</a>'.format(text)
            elif entity.type == MessageEntity.BOLD:
                insert = '<b>' + text + '</b>'
@@ -1040,7 +1082,9 @@ class Message(TelegramObject):

            if entity.type == MessageEntity.TEXT_LINK:
                insert = '[{}]({})'.format(text, entity.url)
-            elif (entity.type == MessageEntity.URL) and urled:
+            elif entity.type == MessageEntity.TEXT_MENTION and entity.user:
+                insert = '[{}](tg://user?id={})'.format(text, entity.user.id)
+            elif entity.type == MessageEntity.URL and urled:
                insert = '[{0}]({0})'.format(text)
            elif entity.type == MessageEntity.BOLD:
                insert = '*' + text + '*'
@@ -55,6 +55,8 @@ class MessageEntity(TelegramObject):
        self.url = url
        self.user = user

+        self._id_attrs = (self.type, self.offset, self.length)
+
    @classmethod
    def de_json(cls, data, bot):
        data = super(MessageEntity, cls).de_json(data, bot)
@@ -39,7 +39,8 @@ class PersonalDetails(TelegramObject):
    """

    def __init__(self, first_name, last_name, birth_date, gender, country_code,
-                 residence_country_code, first_name_native, last_name_native, middle_name=None,
+                 residence_country_code, first_name_native=None,
+                 last_name_native=None, middle_name=None,
                 middle_name_native=None, bot=None, **kwargs):
        # Required
        self.first_name = first_name
@@ -148,8 +148,8 @@ class PassportElementErrorFiles(PassportElementError):
        super(PassportElementErrorFiles, self).__init__('files', type, message)
        self.file_hashes = file_hashes

-        self._id_attrs = ((self.source, self.type, self.message) +
-                          tuple([file_hash for file_hash in file_hashes]))
+        self._id_attrs = ((self.source, self.type, self.message)
+                          + tuple([file_hash for file_hash in file_hashes]))


 class PassportElementErrorFrontSide(PassportElementError):
@@ -323,8 +323,8 @@ class PassportElementErrorTranslationFiles(PassportElementError):
                                                                   type, message)
        self.file_hashes = file_hashes

-        self._id_attrs = ((self.source, self.type, self.message) +
-                          tuple([file_hash for file_hash in file_hashes]))
+        self._id_attrs = ((self.source, self.type, self.message)
+                          + tuple([file_hash for file_hash in file_hashes]))


 class PassportElementErrorUnspecified(PassportElementError):
@@ -64,7 +64,7 @@ class ShippingQuery(TelegramObject):
        data['from_user'] = User.de_json(data.pop('from'), bot)
        data['shipping_address'] = ShippingAddress.de_json(data.get('shipping_address'), bot)

-        return cls(**data)
+        return cls(bot=bot, **data)

    def answer(self, *args, **kwargs):
        """Shortcut for::
@@ -0,0 +1,93 @@
+#!/usr/bin/env python
+# pylint: disable=R0903
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2018
+# 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 Poll."""
+
+from telegram import (TelegramObject)
+
+
+class PollOption(TelegramObject):
+    """
+    This object contains information about one answer option in a poll.
+
+    Attributes:
+        text (:obj:`str`): Option text, 1-100 characters.
+        voter_count (:obj:`int`): Number of users that voted for this option.
+
+    Args:
+        text (:obj:`str`): Option text, 1-100 characters.
+        voter_count (:obj:`int`): Number of users that voted for this option.
+
+    """
+
+    def __init__(self, text, voter_count, **kwargs):
+        self.text = text
+        self.voter_count = voter_count
+
+    @classmethod
+    def de_json(cls, data, bot):
+        if not data:
+            return None
+
+        return cls(**data)
+
+
+class Poll(TelegramObject):
+    """
+    This object contains information about a poll.
+
+    Attributes:
+        id (:obj:`str`): Unique poll identifier.
+        question (:obj:`str`): Poll question, 1-255 characters.
+        options (List[:class:`PollOption`]): List of poll options.
+        is_closed (:obj:`bool`): True, if the poll is closed.
+
+    Args:
+        id (:obj:`str`): Unique poll identifier.
+        question (:obj:`str`): Poll question, 1-255 characters.
+        options (List[:class:`PollOption`]): List of poll options.
+        is_closed (:obj:`bool`): True, if the poll is closed.
+
+    """
+
+    def __init__(self, id, question, options, is_closed, **kwargs):
+        self.id = id
+        self.question = question
+        self.options = options
+        self.is_closed = is_closed
+
+        self._id_attrs = (self.id,)
+
+    @classmethod
+    def de_json(cls, data, bot):
+        if not data:
+            return None
+
+        data = super(Poll, cls).de_json(data, bot)
+
+        data['options'] = [PollOption.de_json(option, bot) for option in data['options']]
+
+        return cls(**data)
+
+    def to_dict(self):
+        data = super(Poll, self).to_dict()
+
+        data['options'] = [x.to_dict() for x in self.options]
+
+        return data
@@ -85,3 +85,131 @@ class ReplyKeyboardMarkup(ReplyMarkup):
                    r.append(button)  # str
            data['keyboard'].append(r)
        return data
+
+    @classmethod
+    def from_button(cls,
+                    button,
+                    resize_keyboard=False,
+                    one_time_keyboard=False,
+                    selective=False,
+                    **kwargs):
+        """Shortcut for::
+
+            ReplyKeyboardMarkup([[button]], **kwargs)
+
+        Return an ReplyKeyboardMarkup from a single KeyboardButton
+
+        Args:
+            button (:class:`telegram.KeyboardButton` | :obj:`str`): The button to use in the markup
+            resize_keyboard (:obj:`bool`, optional): Requests clients to resize the keyboard
+                vertically for optimal fit (e.g., make the keyboard smaller if there are just two
+                rows of buttons). Defaults to false, in which case the custom keyboard is always of
+                the same height as the app's standard keyboard.
+                Defaults to ``False``
+            one_time_keyboard (:obj:`bool`, optional): Requests clients to hide the keyboard as
+                soon as it's been used. The keyboard will still be available, but clients will
+                automatically display the usual letter-keyboard in the chat - the user can press
+                a special button in the input field to see the custom keyboard again.
+                Defaults to ``False``.
+            selective (:obj:`bool`, optional): Use this parameter if you want to show the keyboard
+                to specific users only. Targets:
+
+                1) users that are @mentioned in the text of the Message object
+                2) if the bot's message is a reply (has reply_to_message_id), sender of the
+                    original message.
+
+                Defaults to ``False``.
+            **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+        """
+        return cls([[button]],
+                   resize_keyboard=resize_keyboard,
+                   one_time_keyboard=one_time_keyboard,
+                   selective=selective,
+                   **kwargs)
+
+    @classmethod
+    def from_row(cls,
+                 button_row,
+                 resize_keyboard=False,
+                 one_time_keyboard=False,
+                 selective=False,
+                 **kwargs):
+        """Shortcut for::
+
+            ReplyKeyboardMarkup([button_row], **kwargs)
+
+        Return an ReplyKeyboardMarkup from a single row of KeyboardButtons
+
+        Args:
+            button_row (List[:class:`telegram.KeyboardButton` | :obj:`str`]): The button to use in
+                the markup
+            resize_keyboard (:obj:`bool`, optional): Requests clients to resize the keyboard
+                vertically for optimal fit (e.g., make the keyboard smaller if there are just two
+                rows of buttons). Defaults to false, in which case the custom keyboard is always of
+                the same height as the app's standard keyboard.
+                Defaults to ``False``
+            one_time_keyboard (:obj:`bool`, optional): Requests clients to hide the keyboard as
+                soon as it's been used. The keyboard will still be available, but clients will
+                automatically display the usual letter-keyboard in the chat - the user can press
+                a special button in the input field to see the custom keyboard again.
+                Defaults to ``False``.
+            selective (:obj:`bool`, optional): Use this parameter if you want to show the keyboard
+                to specific users only. Targets:
+
+                1) users that are @mentioned in the text of the Message object
+                2) if the bot's message is a reply (has reply_to_message_id), sender of the
+                    original message.
+
+                Defaults to ``False``.
+            **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+
+        """
+        return cls([button_row],
+                   resize_keyboard=resize_keyboard,
+                   one_time_keyboard=one_time_keyboard,
+                   selective=selective,
+                   **kwargs)
+
+    @classmethod
+    def from_column(cls,
+                    button_column,
+                    resize_keyboard=False,
+                    one_time_keyboard=False,
+                    selective=False,
+                    **kwargs):
+        """Shortcut for::
+
+            ReplyKeyboardMarkup([[button] for button in button_column], **kwargs)
+
+        Return an ReplyKeyboardMarkup from a single column of KeyboardButtons
+
+        Args:
+            button_column (List[:class:`telegram.KeyboardButton` | :obj:`str`]): The button to use
+                in the markup
+            resize_keyboard (:obj:`bool`, optional): Requests clients to resize the keyboard
+                vertically for optimal fit (e.g., make the keyboard smaller if there are just two
+                rows of buttons). Defaults to false, in which case the custom keyboard is always of
+                the same height as the app's standard keyboard.
+                Defaults to ``False``
+            one_time_keyboard (:obj:`bool`, optional): Requests clients to hide the keyboard as
+                soon as it's been used. The keyboard will still be available, but clients will
+                automatically display the usual letter-keyboard in the chat - the user can press
+                a special button in the input field to see the custom keyboard again.
+                Defaults to ``False``.
+            selective (:obj:`bool`, optional): Use this parameter if you want to show the keyboard
+                to specific users only. Targets:
+
+                1) users that are @mentioned in the text of the Message object
+                2) if the bot's message is a reply (has reply_to_message_id), sender of the
+                    original message.
+
+                Defaults to ``False``.
+            **kwargs (:obj:`dict`): Arbitrary keyword arguments.
+
+        """
+        button_grid = [[button] for button in button_column]
+        return cls(button_grid,
+                   resize_keyboard=resize_keyboard,
+                   one_time_keyboard=one_time_keyboard,
+                   selective=selective,
+                   **kwargs)
@@ -19,7 +19,7 @@
 """This module contains an object that represents a Telegram Update."""

 from telegram import (Message, TelegramObject, InlineQuery, ChosenInlineResult,
-                      CallbackQuery, ShippingQuery, PreCheckoutQuery)
+                      CallbackQuery, ShippingQuery, PreCheckoutQuery, Poll)


 class Update(TelegramObject):
@@ -41,6 +41,8 @@ class Update(TelegramObject):
        shipping_query (:class:`telegram.ShippingQuery`): Optional. New incoming shipping query.
        pre_checkout_query (:class:`telegram.PreCheckoutQuery`): Optional. New incoming
            pre-checkout query.
+        poll (:class:`telegram.Poll`): Optional. New poll state. Bots receive only updates
+            about polls, which are sent or stopped by the bot

    Args:
        update_id (:obj:`int`): The update's unique identifier. Update identifiers start from a
@@ -63,6 +65,8 @@ class Update(TelegramObject):
            Only for invoices with flexible price.
        pre_checkout_query (:class:`telegram.PreCheckoutQuery`, optional): New incoming
            pre-checkout query. Contains full information about checkout
+        poll (:class:`telegram.Poll`, optional): New poll state. Bots receive only updates
+            about polls, which are sent or stopped by the bot
        **kwargs (:obj:`dict`): Arbitrary keyword arguments.

    """
@@ -78,6 +82,7 @@ class Update(TelegramObject):
                 callback_query=None,
                 shipping_query=None,
                 pre_checkout_query=None,
+                 poll=None,
                 **kwargs):
        # Required
        self.update_id = int(update_id)
@@ -91,6 +96,7 @@ class Update(TelegramObject):
        self.pre_checkout_query = pre_checkout_query
        self.channel_post = channel_post
        self.edited_channel_post = edited_channel_post
+        self.poll = poll

        self._effective_user = None
        self._effective_chat = None
@@ -102,7 +108,7 @@ class Update(TelegramObject):
    def effective_user(self):
        """
        :class:`telegram.User`: The user that sent this update, no matter what kind of update this
-            is. Will be ``None`` for :attr:`channel_post`.
+            is. Will be ``None`` for :attr:`channel_post` and :attr:`poll`.

        """
        if self._effective_user:
@@ -140,7 +146,7 @@ class Update(TelegramObject):
        :class:`telegram.Chat`: The chat that this update was sent in, no matter what kind of
            update this is. Will be ``None`` for :attr:`inline_query`,
            :attr:`chosen_inline_result`, :attr:`callback_query` from inline messages,
-            :attr:`shipping_query` and :attr:`pre_checkout_query`.
+            :attr:`shipping_query`, :attr:`pre_checkout_query` and :attr:`poll`.

        """
        if self._effective_chat:
@@ -172,7 +178,7 @@ class Update(TelegramObject):
        :class:`telegram.Message`: The message included in this update, no matter what kind of
            update this is. Will be ``None`` for :attr:`inline_query`,
            :attr:`chosen_inline_result`, :attr:`callback_query` from inline messages,
-            :attr:`shipping_query` and :attr:`pre_checkout_query`.
+            :attr:`shipping_query`, :attr:`pre_checkout_query` and :attr:`poll`.

        """
        if self._effective_message:
@@ -215,5 +221,6 @@ class Update(TelegramObject):
        data['pre_checkout_query'] = PreCheckoutQuery.de_json(data.get('pre_checkout_query'), bot)
        data['channel_post'] = Message.de_json(data.get('channel_post'), bot)
        data['edited_channel_post'] = Message.de_json(data.get('edited_channel_post'), bot)
+        data['poll'] = Poll.de_json(data.get('poll'), bot)

        return cls(**data)
--- a/Show More
+++ b/Show More
				`@@ -0,0 +1 @@`
				`AUTHORS.rst /usr/share/doc/python3-telegram-bot`