bump version to 4.0.1

Merge branch 'master' of github.com:python-telegram-bot/python-telegram-bot
bump version to 4.0.0, update CHANGES
2026-06-20 08:05:27 +00:00 · 2016-04-27 01:17:47 +02:00 · 2016-04-27 01:06:58 +02:00 · 2016-04-27 01:02:57 +02:00 · 2016-04-26 19:44:55 -03:00 · 2016-04-27 00:28:21 +02:00
163 changed files with 7732 additions and 2437 deletions
@@ -1,3 +1,23 @@
+**2016-04-27**
+
+*Released 4.0.1*
+
+- Implement Bot API 2.0
+- Almost complete recode of ``Dispatcher``
+- Please read the `Transistion Guide to 4.0 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Transistion-guide-to-Version-4.0>`_
+- **Changes from 4.0rc1**
+    - The syntax of filters for ``MessageHandler`` (upper/lower cases)
+    - Handler groups are now identified by ``int`` only, and ordered
+- **Note:** v4.0 has been skipped due to a PyPI accident
+
+**2016-04-22**
+
+*Released 4.0rc1*
+
+- Implement Bot API 2.0
+- Almost complete recode of ``Dispatcher``
+- Please read the `Transistion Guide to 4.0 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Transistion-guide-to-Version-4.0>`_
+
 **2016-03-22**

 *Released 3.4*
@@ -24,12 +24,6 @@ Setting things up

   ``$ pip install -r requirements-dev.txt``

-5. In order to run tests you need to set the following environment variables:
-
-   ``$ export CHAT_ID=your-chat-id``
-
-   ``$ export TOKEN=your-bot-token``
-
 Finding something to do
 -----------------------

@@ -64,16 +58,24 @@ Here's how to make a one-off code change.

   - For consistency, please conform to `Google Python Style Guide`_ and `Google Python Style Docstrings`_. In addition, code should be formatted consistently with other code around it.

+   - The following exceptions to the above (Google's) style guides applies:
+
+        - Documenting types of global variables and complex types of class members can be done using the Sphinx docstring convention.
+
   - Please ensure that the code you write is well-tested.

   - Don’t break backward compatibility.

   - Add yourself to the AUTHORS.rst_ file in an alphabetical fashion.

-   - Before making a commit ensure that all automated tests still pass:
+   - Before making a commit ensure that all automated tests, pep8 & lint validations still pass:

      ``$ make test``

+      ``$ make pep8``
+
+      ``$ make lint``
+
   - To actually make the commit and push it to your GitHub fork, run:

      ``$ git commit -a -m "your-commit-message-here"``
@@ -3,14 +3,18 @@
   :target: https://github.com/python-telegram-bot/logos
   :alt: python-telegram-bot Logo

-A Python wrapper around the Telegram Bot API.
+Not **just** a Python wrapper around the Telegram Bot API

-*Stay tuned for library updates and new releases on our* `Telegram Channel <http://telegram.me/pythontelegrambotchannel>`_.
+*Stay tuned for library updates and new releases on our* `Telegram Channel <https://telegram.me/pythontelegrambotchannel>`_.

 .. image:: https://img.shields.io/pypi/v/python-telegram-bot.svg
   :target: https://pypi.python.org/pypi/python-telegram-bot
   :alt: PyPi Package Version

+.. image:: https://img.shields.io/pypi/pyversions/python-telegram-bot.svg
+   :target: https://pypi.python.org/pypi/python-telegram-bot
+   :alt: Supported python versions
+
 .. image:: https://img.shields.io/pypi/dm/python-telegram-bot.svg
   :target: https://pypi.python.org/pypi/python-telegram-bot
   :alt: PyPi Package Monthly Download
@@ -20,7 +24,7 @@ A Python wrapper around the Telegram Bot API.
   :alt: Documentation Status

 .. image:: https://img.shields.io/pypi/l/python-telegram-bot.svg
-   :target: http://www.gnu.org/licenses/lgpl-3.0.html
+   :target: https://www.gnu.org/licenses/lgpl-3.0.html
   :alt: LGPLv3 License

 .. image:: https://travis-ci.org/python-telegram-bot/python-telegram-bot.svg?branch=master
@@ -45,11 +49,7 @@ Table of contents

 - `Introduction`_

- `Status`_
-
-  1. `Telegram API support`_
-
-  2. `Python Version support`_
+- `Telegram API support`_

 - `Installing`_

@@ -57,37 +57,33 @@ Table of contents

 - `Getting started`_

-  1. `API`_
+  #. `Learning by example`_

-  2. `Extensions`_
+  #. `API`_

-  3. `JobQueue`_
+  #. `Extensions`_

-  4. `Logging`_
+  #. `JobQueue`_

-  5. `Examples`_
+  #. `Logging`_

-  6. `Documentation`_
+  #. `Documentation`_
+
+- `Getting help`_
+
+- `Contributing`_

 - `License`_

- `Contact`_
-
- `TODO`_
-
 ===============
 _`Introduction`
 ===============

 This library provides a pure Python interface for the `Telegram Bot API <https://core.telegram.org/bots/api>`_. It works with Python versions from 2.6+. It also works with `Google App Engine <https://cloud.google.com/appengine>`_.

-=========
-_`Status`
-=========
-
-----------------------
+=======================
 _`Telegram API support`
-----------------------
+=======================

 ========================= ============
 Telegram Bot API Method   *Supported?*
@@ -108,35 +104,24 @@ getUserProfilePhotos      Yes
 getFile                   Yes
 setWebhook                Yes
 answerInlineQuery         Yes
+kickChatMember            Yes
+unbanChatMember           Yes
+answerCallbackQuery       Yes
+editMessageText           Yes
+editMessageCaption        Yes
+editMessageReplyMarkup    Yes
+answerCallbackQuery       Yes
 ========================= ============

-------------------------
-_`Python Version support`
-------------------------
-
-============== ============
-Python Version *Supported?*
-============== ============
-2.6            Yes
-2.7            Yes
-3.3            Yes
-3.4            Yes
-3.5            Yes
-PyPy           Yes
-PyPy3          Yes
-============== ============
-
 =============
 _`Installing`
 =============

-You can install python-telegram-bot using::
+You can install or upgrade python-telegram-bot with:

-    $ pip install python-telegram-bot
+.. code:: shell

-Or upgrade to the latest version::
-
-    $ pip install python-telegram-bot --upgrade
+    $ pip install python-telegram-bot==4.0rc1 --upgrade

 ===================
 _`Getting the code`
@@ -144,20 +129,28 @@ _`Getting the code`

 The code is hosted at https://github.com/python-telegram-bot/python-telegram-bot

-Check out the latest development version anonymously with::
+Check out the latest development version anonymously with:
+
+.. code:: shell

    $ git clone https://github.com/python-telegram-bot/python-telegram-bot
    $ cd python-telegram-bot

 Install dependencies:

-    $ pip install -r requirements.txt
+.. code:: shell
+
+    $ pip install -r requirements.txt -r requirements-dev.txt

 Run tests:

+.. code:: shell
+
    $ make test

-To see other options available, run:
+To see other available options, run:
+
+.. code:: shell

    $ make help

@@ -167,7 +160,9 @@ _`Getting started`

 View the last release API documentation at: https://core.telegram.org/bots/api

-This library uses the `logging` module. To set up logging to standard output, put::
+This library uses the `logging` module. To set up logging to standard output, put:
+
+.. code:: python

    import logging
    logging.basicConfig(level=logging.DEBUG,
@@ -177,94 +172,153 @@ at the beginning of your script.

 **Note:** The ``telegram.ext`` module will catch errors that would cause the bot to crash. All these are logged to the ``logging`` module, so it's recommended to use this if you are looking for error causes.

+----------------------
+_`Learning by example`
+----------------------
+
+We believe that the best way to learn and understand this simple package is by example. So here are some examples for you to review. Even if it's not your approach for learning, please take a look at ``echobot2`` (below), it is de facto the base for most of the bots out there. Best of all, the code for these examples are released to the public domain, so you can start by grabbing the code and building on top of it.
+
+- `clibot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/clibot.py>`_ has a command line interface.
+
+- `echobot2 <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/echobot2.py>`_ replies back messages.
+
+- `inlinebot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/inlinebot.py>`_ basic example of an `inline bot <https://core.telegram.org/bots/inline>`_
+
+- `state machine bot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/state_machine_bot.py>`_ keeps the state for individual users, useful for multipart conversations
+
+- `timerbot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/timerbot.py>`_ uses the ``JobQueue`` to send timed messages.
+
+Examples using only the API:
+
+- `echobot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/legacy/echobot.py>`_ replies back messages.
+
+- `roboed <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/legacy/roboed.py>`_ talks to `Robô Ed <http://www.ed.conpet.gov.br/br/converse.php>`_.
+
+Look at the examples on the `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Examples>`_ to see other bots the community has built.
+
 ------
 _`API`
 ------

-Note: Using the ``Bot`` class directly is the 'old' method, but almost all of this is still important information, even if you're using the ``telegram.ext`` submodule!
+Note: Using the ``Bot`` class directly is the 'old' method, we have an easier way to make bots described in the next section.  All of this is however still important information, even if you're using the ``telegram.ext`` submodule!

 The API is exposed via the ``telegram.Bot`` class.

-To generate an Access Token you have to talk to `BotFather <https://telegram.me/botfather>`_ and follow a few simple steps (described `here <https://core.telegram.org/bots#botfather>`_).
+To generate an Access Token you have to talk to `BotFather <https://telegram.me/botfather>`_ and follow a few simple steps (described `here <https://core.telegram.org/bots#6-botfather>`_).

 For full details see the `Bots: An introduction for developers <https://core.telegram.org/bots>`_.

-To create an instance of the ``telegram.Bot``::
+To create an instance of the ``telegram.Bot``:
+
+.. code:: python

    >>> import telegram
    >>> bot = telegram.Bot(token='token')

-To see if your credentials are successful::
+To see if your credentials are successful:

-    >>> print bot.getMe()
+.. code:: python
+
+    >>> print(bot.getMe())
    {"first_name": "Toledo's Palace Bot", "username": "ToledosPalaceBot"}

 Bots can't initiate conversations with users. A user must either add them to a group or send them a message first. People can use ``telegram.me/<bot_username>`` links or username search to find your bot.

-To fetch text messages sent to your Bot::
+To fetch text messages sent to your Bot:
+
+.. code:: python

    >>> updates = bot.getUpdates()
-    >>> print [u.message.text for u in updates]
+    >>> print([u.message.text for u in updates])

-To fetch images sent to your Bot::
+To fetch images sent to your Bot:
+
+.. code:: python

    >>> updates = bot.getUpdates()
-    >>> print [u.message.photo for u in updates if u.message.photo]
+    >>> print([u.message.photo for u in updates if u.message.photo])

-To reply messages you'll always need the chat_id::
+To reply messages you'll always need the ``chat_id``:
+
+.. code:: python

    >>> chat_id = bot.getUpdates()[-1].message.chat_id

-To post a text message::
+To post a text message:
+
+.. code:: python

    >>> bot.sendMessage(chat_id=chat_id, text="I'm sorry Dave I'm afraid I can't do that.")

-To post a text message with markdown::
+To post a text message with markdown:
+
+.. code:: python

    >>> bot.sendMessage(chat_id=chat_id, text="*bold* _italic_ [link](http://google.com).", parse_mode=telegram.ParseMode.MARKDOWN)

-To post a text message with Html style::
+To post a text message with Html style:

-	>>> bot.sendMessage(chat_id=chat_id, text="<b>bold</b> <i>italic</i> <a href="http://google.com">link</a>.", parse_mode=telegram.ParseMode.HTML)
+.. code:: python

-To post an Emoji (special thanks to `Tim Whitlock <http://apps.timwhitlock.info/emoji/tables/unicode>`_)::
+	>>> bot.sendMessage(chat_id=chat_id, text='<b>bold</b> <i>italic</i> <a href="http://google.com">link</a>.', parse_mode=telegram.ParseMode.HTML)
+
+To post an Emoji (special thanks to `Tim Whitlock <http://apps.timwhitlock.info/emoji/tables/unicode>`_):
+
+.. code:: python

    >>> bot.sendMessage(chat_id=chat_id, text=telegram.Emoji.PILE_OF_POO)

-To post an image file via URL::
+To post an image file via URL:
+
+.. code:: python

    >>> bot.sendPhoto(chat_id=chat_id, photo='https://telegram.org/img/t_logo.png')

-To post an image file from disk::
+To post an image file from disk:
+
+.. code:: python

    >>> bot.sendPhoto(chat_id=chat_id, photo=open('tests/test.png', 'rb'))

-To post a voice file from disk::
+To post a voice file from disk:
+
+.. code:: python

    >>> bot.sendVoice(chat_id=chat_id, voice=open('tests/telegram.ogg', 'rb'))

-To tell the user that something is happening on bot's side::
+To tell the user that something is happening on bot's side:
+
+.. code:: python

    >>> bot.sendChatAction(chat_id=chat_id, action=telegram.ChatAction.TYPING)

-To create `Custom Keyboards <https://core.telegram.org/bots#keyboards>`_::
+To create `Custom Keyboards <https://core.telegram.org/bots#keyboards>`_:

-    >>> custom_keyboard = [[ telegram.Emoji.THUMBS_UP_SIGN, telegram.Emoji.THUMBS_DOWN_SIGN ]]
+.. code:: python
+
+    >>> custom_keyboard = [[ telegram.KeyboardButton(telegram.Emoji.THUMBS_UP_SIGN),
+    ...     telegram.KeyboardButton(telegram.Emoji.THUMBS_DOWN_SIGN) ]]
    >>> reply_markup = telegram.ReplyKeyboardMarkup(custom_keyboard)
    >>> bot.sendMessage(chat_id=chat_id, text="Stay here, I'll be back.", reply_markup=reply_markup)

-To hide `Custom Keyboards <https://core.telegram.org/bots#keyboards>`_::
+To hide `Custom Keyboards <https://core.telegram.org/bots#keyboards>`_:
+
+.. code:: python

    >>> reply_markup = telegram.ReplyKeyboardHide()
    >>> bot.sendMessage(chat_id=chat_id, text="I'm back.", reply_markup=reply_markup)

-To download a file (you will need its file_id)::
+To download a file (you will need its ``file_id``):
+
+.. code:: python

    >>> file_id = message.voice.file_id
    >>> newFile = bot.getFile(file_id)
    >>> newFile.download('voice.ogg')

-There are many more API methods, to read the full API documentation::
+There are many more API methods, to read the full API documentation:
+
+.. code:: shell

    $ pydoc telegram.Bot

@@ -276,67 +330,93 @@ The ``telegram.ext`` submodule is built on top of the bare-metal API. It provide

 We'll need an Access Token. **Note:** If you have done this in the previous step, you can use that one. To generate an Access Token, we have to talk to `BotFather <https://telegram.me/botfather>`_ and follow a few simple steps (described `here <https://core.telegram.org/bots#botfather>`_).

-First, we create an ``Updater`` object::
+First, we create an ``Updater`` object:
+
+.. code:: python

   >>> from telegram.ext import Updater
   >>> updater = Updater(token='token')

-For quicker access to the ``Dispatcher`` used by our ``Updater``, we can introduce it locally::
+For quicker access to the ``Dispatcher`` used by our ``Updater``, we can introduce it locally:
+
+.. code:: python

   >>> dispatcher = updater.dispatcher

-Now, we need to define a function that should process a specific type of update::
+Now, we need to define a function that should process a specific type of update:
+
+.. code:: python

   >>> def start(bot, update):
   ...   bot.sendMessage(chat_id=update.message.chat_id, text="I'm a bot, please talk to me!")

-We want this function to be called on a Telegram message that contains the ``/start`` command, so we need to register it in the dispatcher::
+We want this function to be called on a Telegram message that contains the ``/start`` command. To do that, we have to use a ``CommandHandler`` object and register it in the dispatcher:

-   >>> dispatcher.addTelegramCommandHandler('start', start)
+.. code:: python

-The last step is to tell the ``Updater`` to start working::
+   >>> from telegram.ext import CommandHandler
+   >>> start_handler = CommandHandler('start', start)
+   >>> dispatcher.addHandler(start_handler)
+
+The last step is to tell the ``Updater`` to start working:
+
+.. code:: python

   >>> updater.start_polling()

-Our bot is now up and running (go ahead and try it)! It's not doing anything yet, besides answering to the ``/start`` command. Let's add another handler function and register it::
+Our bot is now up and running (go ahead and try it)! It's not doing anything yet, besides answering to the ``/start`` command. Let's add another handler that listens for regular messages. We're using the `MessageHandler` here to echo to all text messages:
+
+.. code:: python

   >>> def echo(bot, update):
   ...   bot.sendMessage(chat_id=update.message.chat_id, text=update.message.text)
   ...
-   >>> dispatcher.addTelegramMessageHandler(echo)
+   >>> from telegram.ext import MessageHandler, Filters
+   >>> echo_handler = MessageHandler([Filters.text], echo)
+   >>> dispatcher.addHandler(echo_handler)

-Our bot should now reply to all messages that are not a command with a message that has the same content.
+Our bot should now reply to all text messages that are not a command with a message that has the same content.

-People might try to send commands to the bot that it doesn't understand, so we should get that covered as well::
+Let's add some functionality to our bot. We want to add the ``/caps`` command, that will take some text as parameter and return it in all caps. We can get the arguments that were passed to a command in the handler function:

-   >>> def unknown(bot, update):
-   ...   bot.sendMessage(chat_id=update.message.chat_id, text="Sorry, I didn't understand that command.")
-   ...
-   >>> dispatcher.addUnknownTelegramCommandHandler(unknown)
-
-Let's add some functionality to our bot. We want to add the ``/caps`` command, that will take some text as parameter and return it in all caps. We can get the arguments that were passed to the command in the handler function simply by adding it to the parameter list::
+.. code:: python

   >>> def caps(bot, update, args):
   ...   text_caps = ' '.join(args).upper()
   ...   bot.sendMessage(chat_id=update.message.chat_id, text=text_caps)
   ...
-   >>> dispatcher.addTelegramCommandHandler('caps', caps)
+   >>> caps_handler = CommandHandler('caps', caps, pass_args=True)
+   >>> dispatcher.addHandler(caps_handler)

-To enable our bot to respond to inline queries, we can add the following (you will also have to talk to BotFather)::
+To enable our bot to respond to inline queries, we can add the following (you will also have to talk to BotFather):
+
+.. code:: python

   >>> from telegram import InlineQueryResultArticle
   >>> def inline_caps(bot, update):
-   ...   # If you activated inline feedback, updates might either contain
-   ...   # inline_query or chosen_inline_result, the other one will be None
-   ...   if update.inline_query:
-   ...     query = bot.update.inline_query.query
-   ...     results = list()
-   ...     results.append(InlineQueryResultArticle(query.upper(), 'Caps', text_caps))
-   ...     bot.answerInlineQuery(update.inline_query.id, results)
+   ...   query = bot.update.inline_query.query
+   ...   results = list()
+   ...   results.append(InlineQueryResultArticle(query.upper(), 'Caps', query.upper()))
+   ...   bot.answerInlineQuery(update.inline_query.id, results)
   ...
-   >>> dispatcher.addTelegramInlineHandler(inline_caps)
+   >>> from telegram.ext import InlineQueryHandler
+   >>> inline_caps_handler = InlineQueryHandler(inline_caps)
+   >>> dispatcher.addHandler(inline_caps_handler)

-Now it's time to stop the bot::
+People might try to send commands to the bot that it doesn't understand, so we can use a ``RegexHandler`` to recognize all commands that were not recognized by the previous handlers. **Note:** This handler has to be added last, else it will be triggered before the ``CommandHandlers`` had a chance to look at the update:
+
+.. code:: python
+
+   >>> def unknown(bot, update):
+   ...   bot.sendMessage(chat_id=update.message.chat_id, text="Sorry, I didn't understand that command.")
+   ...
+   >>> from telegram.ext import RegexHandler
+   >>> unknown_handler = RegexHandler(r'/.*', unknown)
+   >>> dispatcher.addHandler(unknown_handler)
+
+If you're done playing around, stop the bot with this:
+
+.. code:: python

   >>> updater.stop()

@@ -346,29 +426,39 @@ Check out more examples in the `examples folder <https://github.com/python-teleg
 _`JobQueue`
 -----------

-The ``JobQueue`` allows you to perform tasks with a delay or even periodically. The ``Updater`` will create one for you::
+The ``JobQueue`` allows you to perform tasks with a delay or even periodically. The ``Updater`` will create one for you:
+
+.. code:: python

    >>> from telegram.ext import Updater
    >>> u = Updater('TOKEN')
    >>> j = u.job_queue

-The job queue uses functions for tasks, so we define one and add it to the queue. Usually, when the first job is added to the queue, it wil start automatically. We can prevent this by setting ``prevent_autostart=True``::
+The job queue uses functions for tasks, so we define one and add it to the queue. Usually, when the first job is added to the queue, it wil start automatically. We can prevent this by setting ``prevent_autostart=True``:
+
+.. code:: python

    >>> def job1(bot):
    ...     bot.sendMessage(chat_id='@examplechannel', text='One message every minute')
    >>> j.put(job1, 60, next_t=0, prevent_autostart=True)

-You can also have a job that will not be executed repeatedly::
+You can also have a job that will not be executed repeatedly:
+
+.. code:: python

    >>> def job2(bot):
    ...     bot.sendMessage(chat_id='@examplechannel', text='A single message with 30s delay')
    >>> j.put(job2, 30, repeat=False)

-Now, because we didn't prevent the auto start this time, the queue will start ticking. It runs in a seperate thread, so it is non-blocking. When we stop the Updater, the related queue will be stopped as well::
+Now, because we didn't prevent the auto start this time, the queue will start ticking. It runs in a seperate thread, so it is non-blocking. When we stop the Updater, the related queue will be stopped as well:
+
+.. code:: python

    >>> u.stop()

-We can also stop the job queue by itself::
+We can also stop the job queue by itself:
+
+.. code:: python

    >>> j.stop()

@@ -376,64 +466,48 @@ We can also stop the job queue by itself::
 _`Logging`
 ----------

-You can get logs in your main application by calling `logging` and setting the log level you want::
+You can get logs in your main application by calling `logging` and setting the log level you want:
+
+.. code:: python

    >>> import logging
    >>> logger = logging.getLogger()
    >>> logger.setLevel(logging.INFO)

-If you want DEBUG logs instead::
+If you want DEBUG logs instead:
+
+.. code:: python

    >>> logger.setLevel(logging.DEBUG)

-----------
-_`Examples`
-----------
-
-Here follows some examples to help you to get your own Bot up to speed:
-
- `echobot2 <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/echobot2.py>`_ replies back messages.
-
- `clibot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/clibot.py>`_ has a command line interface.
-
- `timerbot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/timerbot.py>`_ uses the ``JobQueue`` to send timed messages.
-
- `Welcome Bot <https://github.com/jh0ker/welcomebot>`_ greets everyone who joins a group chat.
-
-Legacy examples (pre-3.0):
-
- `echobot <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/legacy/echobot.py>`_ replies back messages.
-
- `roboed <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/legacy/roboed.py>`_ talks to `Robô Ed <http://www.ed.conpet.gov.br/br/converse.php>`_.
-
- `Simple-Echo-Telegram-Bot <https://github.com/sooyhwang/Simple-Echo-Telegram-Bot>`_ simple Python Telegram bot that echoes your input with Flask microframework, setWebhook method, and Google App Engine (optional) - by @sooyhwang.
-
- `DevOps Reaction Bot <https://github.com/leandrotoledo/gae-devops-reaction-telegram-bot>`_ sends latest or random posts from `DevOps Reaction <http://devopsreactions.tumblr.com/>`_. Running on `Google App Engine <https://cloud.google.com/appengine>`_ (billing has to be enabled for fully Socket API support).
-
-Other notable examples:
-
- `TwitterForwarderBot <https://github.com/franciscod/telegram-twitter-forwarder-bot>`_ forwards you tweets from people that you have subscribed to.

 ================
 _`Documentation`
 ================

-``python-telegram-bot``'s documentation lives at `Read the Docs <http://python-telegram-bot.readthedocs.org/en/latest/>`_.
+``python-telegram-bot``'s documentation lives at `Read the Docs <https://python-telegram-bot.readthedocs.org/en/latest/>`_.
+
+===============
+_`Getting help`
+===============
+
+You can get help in several ways:
+
+1. We have a vibrant community of developers helping each other in our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_. Join us!
+   
+2. You can ask for help on Stack Overflow using the `python-telegram-bot tag <https://stackoverflow.com/questions/tagged/python-telegram-bot>`_.
+   
+3. As last resort, the developers are ready to help you with `serious issues <https://github.com/python-telegram-bot/python-telegram-bot/issues/new>`_.
+
+
+===============
+_`Contributing`
+===============
+
+Contributions of all sizes are welcome. Please review our `contribution guidelines <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/CONTRIBUTING.rst>`_ to get started. You can also help by `reporting bugs <https://github.com/python-telegram-bot/python-telegram-bot/issues/new>`_.

 ==========
 _`License`
 ==========

-You may copy, distribute and modify the software provided that modifications are described and licensed for free under `LGPL-3 <http://www.gnu.org/licenses/lgpl-3.0.html>`_. Derivatives works (including modifications or anything statically linked to the library) can only be redistributed under `LGPL-3 <http://www.gnu.org/licenses/lgpl-3.0.html>`_, but applications that use the library don't have to be.
-
-==========
-_`Contact`
-==========
-
-Feel free to join to our `Telegram group <https://telegram.me/pythontelegrambotgroup>`_.
-
-=======
-_`TODO`
-=======
-
-Patches and bug reports are `welcome <https://github.com/python-telegram-bot/python-telegram-bot/issues/new>`_, just please keep the style consistent with the original source.
+You may copy, distribute and modify the software provided that modifications are described and licensed for free under `LGPL-3 <https://www.gnu.org/licenses/lgpl-3.0.html>`_. Derivatives works (including modifications or anything statically linked to the library) can only be redistributed under `LGPL-3 <https://www.gnu.org/licenses/lgpl-3.0.html>`_, but applications that use the library don't have to be.
@@ -58,9 +58,9 @@ author = u'Leandro Toledo'
 # built documents.
 #
 # The short X.Y version.
-version = '3.4'
+version = '4.0'
 # The full version, including alpha/beta/rc tags.
-release = '3.4.0'
+release = '4.0.1'

 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -3,5 +3,4 @@ telegram.bot module

 .. automodule:: telegram.bot
    :members:
-    :undoc-members:
    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.ext.handler module
+===========================
+
+.. automodule:: telegram.ext.handler
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.ext.choseninlineresulthandler module
+=============================================
+
+.. automodule:: telegram.ext.choseninlineresulthandler
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.ext.commandhandler module
+==================================
+
+.. automodule:: telegram.ext.commandhandler
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.ext.handler module
+===========================
+
+.. automodule:: telegram.ext.handler
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.ext.inlinequeryhandler module
+======================================
+
+.. automodule:: telegram.ext.inlinequeryhandler
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.ext.jobqueue module
+============================
+
+.. automodule:: telegram.ext.jobqueue
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.ext.messagehandler module
+==================================
+
+.. automodule:: telegram.ext.messagehandler
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.ext.regexhandler module
+================================
+
+.. automodule:: telegram.ext.regexhandler
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,28 @@
+telegram.ext package
+====================
+
+Submodules
+----------
+
+.. toctree::
+
+    telegram.ext.updater
+    telegram.ext.dispatcher
+    telegram.ext.jobqueue
+    telegram.ext.handler
+    telegram.ext.choseninlineresulthandler
+    telegram.ext.commandhandler
+    telegram.ext.inlinequeryhandler
+    telegram.ext.messagehandler
+    telegram.ext.regexhandler
+    telegram.ext.stringcommandhandler
+    telegram.ext.stringregexhandler
+    telegram.ext.typehandler
+
+Module contents
+---------------
+
+.. automodule:: telegram.ext
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.ext.stringcommandhandler module
+========================================
+
+.. automodule:: telegram.ext.stringcommandhandler
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.ext.stringregexhandler module
+======================================
+
+.. automodule:: telegram.ext.stringregexhandler
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.ext.typehandler module
+===============================
+
+.. automodule:: telegram.ext.typehandler
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinekeyboardbutton module
+===========================
+
+.. automodule:: telegram.inlinekeyboardbutton
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinekeyboardmarkup module
+==========================
+
+.. automodule:: telegram.inlinekeyboardmarkup
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinequeryresultarticle module
+=================================
+
+.. automodule:: telegram.inlinequeryresultarticle
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinequeryresultaudio module
+=================================
+
+.. automodule:: telegram.inlinequeryresultaudio
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinequeryresultcachedaudio module
+=================================
+
+.. automodule:: telegram.inlinequeryresultcachedaudio
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinequeryresultcacheddocument module
+=================================
+
+.. automodule:: telegram.inlinequeryresultcacheddocument
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinequeryresultcachedgif module
+=================================
+
+.. automodule:: telegram.inlinequeryresultcachedgif
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinequeryresultcachedmpeg4gif module
+=================================
+
+.. automodule:: telegram.inlinequeryresultcachedmpeg4gif
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinequeryresultcachedphoto module
+=================================
+
+.. automodule:: telegram.inlinequeryresultcachedphoto
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinequeryresultcachedsticker module
+=================================
+
+.. automodule:: telegram.inlinequeryresultcachedsticker
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinequeryresultcachedvideo module
+=================================
+
+.. automodule:: telegram.inlinequeryresultcachedvideo
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinequeryresultcachedvoice module
+=================================
+
+.. automodule:: telegram.inlinequeryresultcachedvoice
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinequeryresultcontact module
+=================================
+
+.. automodule:: telegram.inlinequeryresultcontact
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinequeryresultdocument module
+=================================
+
+.. automodule:: telegram.inlinequeryresultdocument
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinequeryresultgif module
+=================================
+
+.. automodule:: telegram.inlinequeryresultgif
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinequeryresultlocation module
+=================================
+
+.. automodule:: telegram.inlinequeryresultlocation
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinequeryresultmpeg4gif module
+=================================
+
+.. automodule:: telegram.inlinequeryresultmpeg4gif
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinequeryresultphoto module
+=================================
+
+.. automodule:: telegram.inlinequeryresultphoto
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinequeryresultvenue module
+=================================
+
+.. automodule:: telegram.inlinequeryresultvenue
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinequeryresultvideo module
+=================================
+
+.. automodule:: telegram.inlinequeryresultvideo
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -0,0 +1,7 @@
+telegram.inlinequeryresultvoice module
+=================================
+
+.. automodule:: telegram.inlinequeryresultvoice
+    :members:
+    :undoc-members:
+    :show-inheritance:
@@ -1,7 +0,0 @@
-telegram.jobqueue module
-========================
-
-.. automodule:: telegram.jobqueue
-    :members:
-    :undoc-members:
-    :show-inheritance:
@@ -9,11 +9,30 @@ Submodules
   telegram.audio
   telegram.base
   telegram.bot
-   telegram.ext.updater
-   telegram.ext.dispatcher
-   telegram.jobqueue
+   telegram.ext
   telegram.inlinequery
   telegram.inlinequeryresult
+   telegram.inlinekeyboardbutton
+   telegram.inlinekeyboardmarkup
+   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.inlinequeryresultgif
+   telegram.inlinequeryresultlocation
+   telegram.inlinequeryresultmpeg4gif
+   telegram.inlinequeryresultphoto
+   telegram.inlinequeryresultvenue
+   telegram.inlinequeryresultvideo
+   telegram.inlinequeryresultvoice
   telegram.choseninlineresult
   telegram.chataction
   telegram.contact
@@ -18,7 +18,8 @@ Reply to last chat from the command line by typing "/reply <text>"
 Type 'stop' on the command line to stop the bot.
 """

-from telegram.ext import Updater
+from telegram.ext import Updater, StringCommandHandler, StringRegexHandler, \
+    MessageHandler, CommandHandler, RegexHandler, Filters
 from telegram.ext.dispatcher import run_async
 from time import sleep
 import logging
@@ -34,8 +35,9 @@ logger = logging.getLogger(__name__)
 last_chat_id = 0


-# Define a few (command) handlers. These usually take the two arguments bot and
-# update. Error handlers also receive the raised TelegramError object in error.
+# Define a few (command) handler callback functions. These usually take the
+# two arguments bot and update. Error handlers also receive the raised
+# TelegramError object in error.
 def start(bot, update):
    """ Answer in Telegram """
    bot.sendMessage(update.message.chat_id, text='Hi!')
@@ -59,13 +61,8 @@ def any_message(bot, update):
                 update.message.text))


-def unknown_command(bot, update):
-    """ Answer in Telegram """
-    bot.sendMessage(update.message.chat_id, text='Command not recognized!')
-
-
@run_async
-def message(bot, update, **kwargs):
+def message(bot, update):
    """
    Example for an asynchronous handler. It's not guaranteed that replies will
    be in order when using @run_async. Also, you have to include **kwargs in
@@ -95,16 +92,12 @@ def cli_noncommand(bot, update, update_queue):
    appending it to the argument list. Be careful with this though.
    Here, we put the input string back into the queue, but as a command.

-    To learn more about those optional handler parameters, read:
-    http://python-telegram-bot.readthedocs.org/en/latest/telegram.dispatcher.html
+    To learn more about those optional handler parameters, read the
+    documentation of the Handler classes.
    """
    update_queue.put('/%s' % update)


-def unknown_cli_command(bot, update):
-    logger.warn("Command not found: %s" % update)
-
-
 def error(bot, update, error):
    """ Print error to console """
    logger.warn('Update %s caused error %s' % (update, error))
@@ -119,42 +112,43 @@ def main():
    dp = updater.dispatcher

    # This is how we add handlers for Telegram messages
-    dp.addTelegramCommandHandler("start", start)
-    dp.addTelegramCommandHandler("help", help)
-    dp.addUnknownTelegramCommandHandler(unknown_command)
+    dp.addHandler(CommandHandler("start", start))
+    dp.addHandler(CommandHandler("help", help))
    # Message handlers only receive updates that don't contain commands
-    dp.addTelegramMessageHandler(message)
-    # Regex handlers will receive all updates on which their regex matches
-    dp.addTelegramRegexHandler('.*', any_message)
+    dp.addHandler(MessageHandler([Filters.text], message))
+    # Regex handlers will receive all updates on which their regex matches,
+    # but we have to add it in a separate group, since in one group,
+    # only one handler will be executed
+    dp.addHandler(RegexHandler('.*', any_message), group='log')

-    # String handlers work pretty much the same
-    dp.addStringCommandHandler('reply', cli_reply)
-    dp.addUnknownStringCommandHandler(unknown_cli_command)
-    dp.addStringRegexHandler('[^/].*', cli_noncommand)
+    # String handlers work pretty much the same. Note that we have to tell
+    # the handler to pass the args or update_queue parameter
+    dp.addHandler(StringCommandHandler('reply', cli_reply, pass_args=True))
+    dp.addHandler(StringRegexHandler('[^/].*', cli_noncommand,
+                                     pass_update_queue=True))

    # All TelegramErrors are caught for you and delivered to the error
    # handler(s). Other types of Errors are not caught.
    dp.addErrorHandler(error)

    # Start the Bot and store the update Queue, so we can insert updates
-    update_queue = updater.start_polling(poll_interval=0.1, timeout=10)
+    update_queue = updater.start_polling(timeout=10)

    '''
    # Alternatively, run with webhook:
-    updater.bot.setWebhook(webhook_url='https://example.com/%s' % token,
-                           certificate=open('cert.pem', 'rb'))

    update_queue = updater.start_webhook('0.0.0.0',
                                         443,
                                         url_path=token,
                                         cert='cert.pem',
-                                         key='key.key')
+                                         key='key.key',
+                                         webhook_url='https://example.com/%s'
+                                             % token)

    # Or, if SSL is handled by a reverse proxy, the webhook URL is already set
    # and the reverse proxy is configured to deliver directly to port 6000:

-    update_queue = updater.start_webhook('0.0.0.0',
-                                         6000)
+    update_queue = updater.start_webhook('0.0.0.0', 6000)
    '''

    # Start CLI-Loop
@@ -17,7 +17,7 @@ Press Ctrl-C on the command line or send a signal to the process to stop the
 bot.
 """

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

 # Enable logging
@@ -54,11 +54,11 @@ def main():
    dp = updater.dispatcher

    # on different commands - answer in Telegram
-    dp.addTelegramCommandHandler("start", start)
-    dp.addTelegramCommandHandler("help", help)
+    dp.addHandler(CommandHandler("start", start))
+    dp.addHandler(CommandHandler("help", help))

    # on noncommand i.e message - echo the message on Telegram
-    dp.addTelegramMessageHandler(echo)
+    dp.addHandler(MessageHandler([Filters.text], echo))

    # log all errors
    dp.addErrorHandler(error)
@@ -16,12 +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.
 """
-from random import getrandbits
+from uuid import uuid4

 import re

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

 # Enable logging
@@ -49,29 +50,29 @@ def escape_markdown(text):


 def inlinequery(bot, update):
-    if update.inline_query is not None and update.inline_query.query:
-        query = update.inline_query.query
-        results = list()
+    query = update.inline_query.query
+    results = list()

-        results.append(InlineQueryResultArticle(
-                id=hex(getrandbits(64))[2:],
-                title="Caps",
-                message_text=query.upper()))
+    results.append(InlineQueryResultArticle(
+            id=uuid4(),
+            title="Caps",
+            input_message_content=InputTextMessageContent(query.upper())))

-        results.append(InlineQueryResultArticle(
-                id=hex(getrandbits(64))[2:],
-                title="Bold",
-                message_text="*%s*" % escape_markdown(query),
-                parse_mode=ParseMode.MARKDOWN))
+    results.append(InlineQueryResultArticle(
+            id=uuid4(),
+            title="Bold",
+            input_message_content=InputTextMessageContent(
+                "*%s*" % escape_markdown(query),
+                parse_mode=ParseMode.MARKDOWN)))

-        results.append(InlineQueryResultArticle(
-                id=hex(getrandbits(64))[2:],
-                title="Italic",
-                message_text="_%s_" % escape_markdown(query),
-                parse_mode=ParseMode.MARKDOWN))
-
-        bot.answerInlineQuery(update.inline_query.id, results=results)
+    results.append(InlineQueryResultArticle(
+            id=uuid4(),
+            title="Italic",
+            input_message_content=InputTextMessageContent(
+                "_%s_" % escape_markdown(query),
+                parse_mode=ParseMode.MARKDOWN)))

+    bot.answerInlineQuery(update.inline_query.id, results=results)


 def error(bot, update, error):
@@ -86,11 +87,11 @@ def main():
    dp = updater.dispatcher

    # on different commands - answer in Telegram
-    dp.addTelegramCommandHandler("start", start)
-    dp.addTelegramCommandHandler("help", help)
+    dp.addHandler(CommandHandler("start", start))
+    dp.addHandler(CommandHandler("help", help))

    # on noncommand i.e message - echo the message on Telegram
-    dp.addTelegramInlineHandler(inlinequery)
+    dp.addHandler(InlineQueryHandler(inlinequery))

    # log all errors
    dp.addErrorHandler(error)
@@ -0,0 +1,120 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# Basic example for a bot that awaits an answer from the user. It's built upon
+# the state_machine_bot.py example
+# This program is dedicated to the public domain under the CC0 license.
+
+import logging
+from telegram import Emoji, ForceReply, InlineKeyboardButton, \
+    InlineKeyboardMarkup
+from telegram.ext import Updater, CommandHandler, MessageHandler, \
+    CallbackQueryHandler, Filters
+
+logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - '
+                           '%(message)s',
+                    level=logging.DEBUG)
+
+# Define the different states a chat can be in
+MENU, AWAIT_CONFIRMATION, AWAIT_INPUT = range(3)
+
+# Python 2 and 3 unicode differences
+try:
+    YES, NO = (Emoji.THUMBS_UP_SIGN.decode('utf-8'),
+               Emoji.THUMBS_DOWN_SIGN.decode('utf-8'))
+except AttributeError:
+    YES, NO = (Emoji.THUMBS_UP_SIGN, Emoji.THUMBS_DOWN_SIGN)
+
+# States are saved in a dict that maps chat_id -> state
+state = dict()
+# Sometimes you need to save data temporarily
+context = dict()
+# This dict is used to store the settings value for the chat.
+# Usually, you'd use persistence for this (e.g. sqlite).
+values = dict()
+
+
+# Example handler. Will be called on the /set command and on regular messages
+def set_value(bot, update):
+    chat_id = update.message.chat_id
+    user_id = update.message.from_user.id
+    user_state = state.get(chat_id, MENU)
+
+    if user_state == MENU:
+        state[user_id] = AWAIT_INPUT  # set the state
+        bot.sendMessage(chat_id,
+                        text="Please enter your settings value",
+                        reply_markup=ForceReply())
+
+
+def entered_value(bot, update):
+    chat_id = update.message.chat_id
+    user_id = update.message.from_user.id
+    chat_state = state.get(user_id, MENU)
+
+    # Check if we are waiting for input
+    if chat_state == AWAIT_INPUT:
+        state[user_id] = AWAIT_CONFIRMATION
+
+        # Save the user id and the answer to context
+        context[user_id] = update.message.text
+        reply_markup = InlineKeyboardMarkup(
+            [[InlineKeyboardButton(YES, callback_data=YES),
+              InlineKeyboardButton(NO, callback_data=NO)]])
+        bot.sendMessage(chat_id, text="Are you sure?",
+                        reply_markup=reply_markup)
+
+
+def confirm_value(bot, update):
+    query = update.callback_query
+    chat_id = query.message.chat_id
+    user_id = query.from_user.id
+    text = query.data
+    user_state = state.get(user_id, MENU)
+    user_context = context.get(user_id, None)
+
+    # Check if we are waiting for confirmation and the right user answered
+    if user_state == AWAIT_CONFIRMATION:
+        del state[user_id]
+        del context[user_id]
+        bot.answerCallbackQuery(query.id, text="Ok!")
+        if text == YES:
+            values[user_id] = user_context
+            bot.editMessageText(text="Changed value to %s." % values[user_id],
+                                chat_id=chat_id,
+                                message_id=
+                                query.message.message_id)
+        else:
+            bot.editMessageText(text="Alright, value is still %s."
+                                     % values.get(user_id, 'not set'),
+                                chat_id=chat_id,
+                                message_id=
+                                query.message.message_id)
+
+
+def help(bot, update):
+    bot.sendMessage(update.message.chat_id, text="Use /set to test this bot.")
+
+
+def error(bot, update, error):
+    logging.warning('Update "%s" caused error "%s"' % (update, error))
+
+# Create the Updater and pass it your bot's token.
+updater = Updater("TOKEN")
+
+# The command
+updater.dispatcher.addHandler(CommandHandler('set', set_value))
+# The answer
+updater.dispatcher.addHandler(MessageHandler([Filters.text], entered_value))
+# The confirmation
+updater.dispatcher.addHandler(CallbackQueryHandler(confirm_value))
+updater.dispatcher.addHandler(CommandHandler('start', help))
+updater.dispatcher.addHandler(CommandHandler('help', help))
+updater.dispatcher.addErrorHandler(error)
+
+# Start the Bot
+updater.start_polling()
+
+# Run the bot until the user presses Ctrl-C or the process receives SIGINT,
+# SIGTERM or SIGABRT
+updater.idle()
@@ -5,7 +5,8 @@
 # This program is dedicated to the public domain under the CC0 license.

 import logging
-from telegram import Updater, ReplyKeyboardMarkup, Emoji, ForceReply
+from telegram import Emoji, ForceReply, ReplyKeyboardMarkup, KeyboardButton
+from telegram.ext import Updater, CommandHandler, MessageHandler, Filters

 logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - '
                           '%(message)s',
@@ -54,14 +55,16 @@ def set_value(bot, update):

        # Save the user id and the answer to context
        context[chat_id] = (user_id, update.message.text)
-        reply_markup = ReplyKeyboardMarkup([[YES, NO]], one_time_keyboard=True)
+        reply_markup = ReplyKeyboardMarkup(
+            [[KeyboardButton(YES), KeyboardButton(NO)]],
+            one_time_keyboard=True)
        bot.sendMessage(chat_id, text="Are you sure?",
                        reply_markup=reply_markup)

    # If we are waiting for confirmation and the right user answered
    elif chat_state == AWAIT_CONFIRMATION and chat_context[0] == user_id:
-        state[chat_id] = MENU
-        context[chat_id] = None
+        del state[chat_id]
+        del context[chat_id]
        if text == YES:
            values[chat_id] = chat_context[1]
            bot.sendMessage(chat_id,
@@ -76,8 +79,8 @@ def set_value(bot, update):
 # Sets the state back to MENU and clears the context
 def cancel(bot, update):
    chat_id = update.message.chat_id
-    state[chat_id] = MENU
-    context[chat_id] = None
+    del state[chat_id]
+    del context[chat_id]


 def help(bot, update):
@@ -88,12 +91,12 @@ def help(bot, update):
 updater = Updater("TOKEN")

 # The command
-updater.dispatcher.addTelegramCommandHandler('set', set_value)
+updater.dispatcher.addHandler(CommandHandler('set', set_value))
 # The answer and confirmation
-updater.dispatcher.addTelegramMessageHandler(set_value)
-updater.dispatcher.addTelegramCommandHandler('cancel', cancel)
-updater.dispatcher.addTelegramCommandHandler('start', help)
-updater.dispatcher.addTelegramCommandHandler('help', help)
+updater.dispatcher.addHandler(MessageHandler([Filters.text], set_value))
+updater.dispatcher.addHandler(CommandHandler('cancel', cancel))
+updater.dispatcher.addHandler(CommandHandler('start', help))
+updater.dispatcher.addHandler(CommandHandler('help', help))

 # Start the Bot
 updater.start_polling()
@@ -18,7 +18,7 @@ Press Ctrl-C on the command line or send a signal to the process to stop the
 bot.
 """

-from telegram.ext import Updater
+from telegram.ext import Updater, CommandHandler
 import logging

 # Enable logging
@@ -44,7 +44,7 @@ def set(bot, update, args):
        # args[0] should contain the time for the timer in seconds
        due = int(args[0])
        if due < 0:
-                bot.sendMessage(chat_id,text='Sorry we can not go back to future!')
+                bot.sendMessage(chat_id, text='Sorry we can not go back to future!')
        def alarm(bot):
            """ Inner function to send the alarm message """
            bot.sendMessage(chat_id, text='Beep!')
@@ -73,9 +73,9 @@ def main():
    dp = updater.dispatcher

    # on different commands - answer in Telegram
-    dp.addTelegramCommandHandler("start", start)
-    dp.addTelegramCommandHandler("help", start)
-    dp.addTelegramCommandHandler("set", set)
+    dp.addHandler(CommandHandler("start", start))
+    dp.addHandler(CommandHandler("help", start))
+    dp.addHandler(CommandHandler("set", set))

    # log all errors
    dp.addErrorHandler(error)
@@ -26,7 +26,7 @@ def requirements():

 setup(
    name='python-telegram-bot',
-    version='3.4',
+    version='4.0.1',
    author='Leandro Toledo',
    author_email='devs@python-telegram-bot.org',
    license='LGPLv3',
@@ -30,8 +30,10 @@ from .sticker import Sticker
 from .video import Video
 from .contact import Contact
 from .location import Location
+from .venue import Venue
 from .chataction import ChatAction
 from .userprofilephotos import UserProfilePhotos
+from .keyboardbutton import KeyboardButton
 from .replymarkup import ReplyMarkup
 from .replykeyboardmarkup import ReplyKeyboardMarkup
 from .replykeyboardhide import ReplyKeyboardHide
@@ -42,55 +44,101 @@ from .file import File
 from .nullhandler import NullHandler
 from .emoji import Emoji
 from .parsemode import ParseMode
+from .messageentity import MessageEntity
 from .message import Message
-from .inlinequery import InlineQuery
+from .inputmessagecontent import InputMessageContent
+from .callbackquery import CallbackQuery
 from .choseninlineresult import ChosenInlineResult
-from .inlinequeryresult import InlineQueryResultArticle, InlineQueryResultGif,\
-    InlineQueryResultMpeg4Gif, InlineQueryResultPhoto, InlineQueryResultVideo
+from .inlinekeyboardbutton import InlineKeyboardButton
+from .inlinekeyboardmarkup import InlineKeyboardMarkup
+from .inlinequery import InlineQuery
+from .inlinequeryresult import InlineQueryResult
+from .inlinequeryresultarticle import InlineQueryResultArticle
+from .inlinequeryresultaudio import InlineQueryResultAudio
+from .inlinequeryresultcachedaudio import InlineQueryResultCachedAudio
+from .inlinequeryresultcacheddocument import InlineQueryResultCachedDocument
+from .inlinequeryresultcachedgif import InlineQueryResultCachedGif
+from .inlinequeryresultcachedmpeg4gif import InlineQueryResultCachedMpeg4Gif
+from .inlinequeryresultcachedphoto import InlineQueryResultCachedPhoto
+from .inlinequeryresultcachedsticker import InlineQueryResultCachedSticker
+from .inlinequeryresultcachedvideo import InlineQueryResultCachedVideo
+from .inlinequeryresultcachedvoice import InlineQueryResultCachedVoice
+from .inlinequeryresultcontact import InlineQueryResultContact
+from .inlinequeryresultdocument import InlineQueryResultDocument
+from .inlinequeryresultgif import InlineQueryResultGif
+from .inlinequeryresultlocation import InlineQueryResultLocation
+from .inlinequeryresultmpeg4gif import InlineQueryResultMpeg4Gif
+from .inlinequeryresultphoto import InlineQueryResultPhoto
+from .inlinequeryresultvenue import InlineQueryResultVenue
+from .inlinequeryresultvideo import InlineQueryResultVideo
+from .inlinequeryresultvoice import InlineQueryResultVoice
+from .inputtextmessagecontent import InputTextMessageContent
+from .inputlocationmessagecontent import InputLocationMessageContent
+from .inputvenuemessagecontent import InputVenueMessageContent
+from .inputcontactmessagecontent import InputContactMessageContent
 from .update import Update
 from .bot import Bot


-def Updater(*args, **kwargs):
-    """
-    Load the updater module on invocation and return an Updater instance.
-    """
-    import warnings
-    warnings.warn("telegram.Updater is being deprecated, please use "
-                  "telegram.ext.Updater from now on.")
-    from .ext.updater import Updater as Up
-    return Up(*args, **kwargs)
-
-
-def Dispatcher(*args, **kwargs):
-    """
-    Load the dispatcher module on invocation and return an Dispatcher instance.
-    """
-    import warnings
-    warnings.warn("telegram.Dispatcher is being deprecated, please use "
-                  "telegram.ext.Dispatcher from now on.")
-    from .ext.dispatcher import Dispatcher as Dis
-    return Dis(*args, **kwargs)
-
-
-def JobQueue(*args, **kwargs):
-    """
-    Load the jobqueue module on invocation and return a JobQueue instance.
-    """
-    import warnings
-    warnings.warn("telegram.JobQueue is being deprecated, please use "
-                  "telegram.ext.JobQueue from now on.")
-    from .ext.jobqueue import JobQueue as JobQ
-    return JobQ(*args, **kwargs)
-
-
 __author__ = 'devs@python-telegram-bot.org'
-__version__ = '3.4'
-__all__ = ('Audio', 'Bot', 'Chat', 'Emoji', 'TelegramError', 'InputFile',
-           'Contact', 'ForceReply', 'ReplyKeyboardHide', 'ReplyKeyboardMarkup',
-           'UserProfilePhotos', 'ChatAction', 'Location', 'Video', 'Document',
-           'Sticker', 'File', 'PhotoSize', 'Update', 'ParseMode', 'Message',
-           'User', 'TelegramObject', 'NullHandler', 'Voice', 'InlineQuery',
-           'ReplyMarkup', 'ChosenInlineResult', 'InlineQueryResultArticle',
-           'InlineQueryResultGif', 'InlineQueryResultPhoto',
-           'InlineQueryResultMpeg4Gif', 'InlineQueryResultVideo')
+__version__ = '4.0.1'
+__all__ = ['Audio',
+           'Bot',
+           'Chat',
+           'ChatAction',
+           'ChosenInlineResult',
+           'CallbackQuery',
+           'Contact',
+           'Document',
+           'Emoji',
+           'File',
+           'ForceReply',
+           'InlineKeyboardButton',
+           'InlineKeyboardMarkup',
+           'InlineQuery',
+           'InlineQueryResult',
+           'InlineQueryResult',
+           'InlineQueryResultArticle',
+           'InlineQueryResultAudio',
+           'InlineQueryResultCachedAudio',
+           'InlineQueryResultCachedDocument',
+           'InlineQueryResultCachedGif',
+           'InlineQueryResultCachedMpeg4Gif',
+           'InlineQueryResultCachedPhoto',
+           'InlineQueryResultCachedSticker',
+           'InlineQueryResultCachedVideo',
+           'InlineQueryResultCachedVoice',
+           'InlineQueryResultContact',
+           'InlineQueryResultDocument',
+           'InlineQueryResultGif',
+           'InlineQueryResultLocation',
+           'InlineQueryResultMpeg4Gif',
+           'InlineQueryResultPhoto',
+           'InlineQueryResultVenue',
+           'InlineQueryResultVideo',
+           'InlineQueryResultVoice',
+           'InputContactMessageContent',
+           'InputFile',
+           'InputLocationMessageContent',
+           'InputMessageContent',
+           'InputTextMessageContent',
+           'InputVenueMessageContent',
+           'KeyboardButton',
+           'Location',
+           'Message',
+           'MessageEntity',
+           'NullHandler',
+           'ParseMode',
+           'PhotoSize',
+           'ReplyKeyboardHide',
+           'ReplyKeyboardMarkup',
+           'ReplyMarkup',
+           'Sticker',
+           'TelegramError',
+           'TelegramObject',
+           'Update',
+           'User',
+           'UserProfilePhotos',
+           'Venue',
+           'Video',
+           'Voice']
@@ -43,7 +43,12 @@ class TelegramObject(object):
        Returns:
            telegram.TelegramObject:
        """
-        raise NotImplementedError
+        if not data:
+            return None
+
+        data = data.copy()
+
+        return data

    def to_json(self):
        """
@@ -59,8 +64,9 @@ class TelegramObject(object):
        """
        data = dict()

-        for key, value in self.__dict__.items():
-            if value:
+        for key in iter(self.__dict__):
+            value = self.__dict__[key]
+            if value is not None:
                if hasattr(value, 'to_dict'):
                    data[key] = value.to_dict()
                else:
@@ -0,0 +1,50 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 a object that represents a Telegram
+CallbackQuery"""
+
+from telegram import TelegramObject, Message, User
+
+
+class CallbackQuery(TelegramObject):
+    """This object represents a Telegram CallbackQuery."""
+
+    def __init__(self,
+                 id,
+                 from_user,
+                 data,
+                 **kwargs):
+        # Required
+        self.id = id
+        self.from_user = from_user
+        self.data = data
+        # Optionals
+        self.message = kwargs.get('message')
+        self.inline_message_id = kwargs.get('inline_message_id', '')
+
+    @staticmethod
+    def de_json(data):
+        if not data:
+            return None
+
+        data['from_user'] = User.de_json(data.get('from'))
+        data['message'] = Message.de_json(data.get('message'))
+
+        return CallbackQuery(**data)
@@ -21,8 +21,7 @@
 This module contains a object that represents a Telegram ChosenInlineResult
 """

-
-from telegram import TelegramObject, User
+from telegram import TelegramObject, User, Location


 class ChosenInlineResult(TelegramObject):
@@ -46,11 +45,16 @@ class ChosenInlineResult(TelegramObject):
    def __init__(self,
                 result_id,
                 from_user,
-                 query):
+                 query,
+                 location=None,
+                 inline_message_id=None):
        # Required
        self.result_id = result_id
        self.from_user = from_user
        self.query = query
+        # Optionals
+        self.location = location
+        self.inline_message_id = inline_message_id

    @staticmethod
    def de_json(data):
@@ -63,8 +67,11 @@ class ChosenInlineResult(TelegramObject):
        """
        if not data:
            return None
-        data = data.copy()
+
+        # Required
        data['from_user'] = User.de_json(data.pop('from'))
+        # Optionals
+        data['location'] = Location.de_json(data.get('location'))

        return ChosenInlineResult(**data)

@@ -163,25 +163,25 @@ class Emoji(object):
    SQUARED_SOS = n(b'\xF0\x9F\x86\x98')
    SQUARED_UP_WITH_EXCLAMATION_MARK = n(b'\xF0\x9F\x86\x99')
    SQUARED_VS = n(b'\xF0\x9F\x86\x9A')
-    REGIONAL_INDICATOR_SYMBOL_LETTER_D_PLUS_REGIONAL_INDICATOR_SYMBOL_LETTER_E\
+    REGIONAL_INDICATOR_SYMBOL_LETTER_D_PLUS_REGIONAL_INDICATOR_SYMBOL_LETTER_E \
        = n(b'\xF0\x9F\x87\xA9\xF0\x9F\x87\xAA')
-    REGIONAL_INDICATOR_SYMBOL_LETTER_G_PLUS_REGIONAL_INDICATOR_SYMBOL_LETTER_B\
+    REGIONAL_INDICATOR_SYMBOL_LETTER_G_PLUS_REGIONAL_INDICATOR_SYMBOL_LETTER_B \
        = n(b'\xF0\x9F\x87\xAC\xF0\x9F\x87\xA7')
-    REGIONAL_INDICATOR_SYMBOL_LETTER_C_PLUS_REGIONAL_INDICATOR_SYMBOL_LETTER_N\
+    REGIONAL_INDICATOR_SYMBOL_LETTER_C_PLUS_REGIONAL_INDICATOR_SYMBOL_LETTER_N \
        = n(b'\xF0\x9F\x87\xA8\xF0\x9F\x87\xB3')
-    REGIONAL_INDICATOR_SYMBOL_LETTER_J_PLUS_REGIONAL_INDICATOR_SYMBOL_LETTER_P\
+    REGIONAL_INDICATOR_SYMBOL_LETTER_J_PLUS_REGIONAL_INDICATOR_SYMBOL_LETTER_P \
        = n(b'\xF0\x9F\x87\xAF\xF0\x9F\x87\xB5')
-    REGIONAL_INDICATOR_SYMBOL_LETTER_K_PLUS_REGIONAL_INDICATOR_SYMBOL_LETTER_R\
+    REGIONAL_INDICATOR_SYMBOL_LETTER_K_PLUS_REGIONAL_INDICATOR_SYMBOL_LETTER_R \
        = n(b'\xF0\x9F\x87\xB0\xF0\x9F\x87\xB7')
-    REGIONAL_INDICATOR_SYMBOL_LETTER_F_PLUS_REGIONAL_INDICATOR_SYMBOL_LETTER_R\
+    REGIONAL_INDICATOR_SYMBOL_LETTER_F_PLUS_REGIONAL_INDICATOR_SYMBOL_LETTER_R \
        = n(b'\xF0\x9F\x87\xAB\xF0\x9F\x87\xB7')
-    REGIONAL_INDICATOR_SYMBOL_LETTER_E_PLUS_REGIONAL_INDICATOR_SYMBOL_LETTER_S\
+    REGIONAL_INDICATOR_SYMBOL_LETTER_E_PLUS_REGIONAL_INDICATOR_SYMBOL_LETTER_S \
        = n(b'\xF0\x9F\x87\xAA\xF0\x9F\x87\xB8')
-    REGIONAL_INDICATOR_SYMBOL_LETTER_I_PLUS_REGIONAL_INDICATOR_SYMBOL_LETTER_T\
+    REGIONAL_INDICATOR_SYMBOL_LETTER_I_PLUS_REGIONAL_INDICATOR_SYMBOL_LETTER_T \
        = n(b'\xF0\x9F\x87\xAE\xF0\x9F\x87\xB9')
-    REGIONAL_INDICATOR_SYMBOL_LETTER_U_PLUS_REGIONAL_INDICATOR_SYMBOL_LETTER_S\
+    REGIONAL_INDICATOR_SYMBOL_LETTER_U_PLUS_REGIONAL_INDICATOR_SYMBOL_LETTER_S \
        = n(b'\xF0\x9F\x87\xBA\xF0\x9F\x87\xB8')
-    REGIONAL_INDICATOR_SYMBOL_LETTER_R_PLUS_REGIONAL_INDICATOR_SYMBOL_LETTER_U\
+    REGIONAL_INDICATOR_SYMBOL_LETTER_R_PLUS_REGIONAL_INDICATOR_SYMBOL_LETTER_U \
        = n(b'\xF0\x9F\x87\xB7\xF0\x9F\x87\xBA')
    SQUARED_KATAKANA_KOKO = n(b'\xF0\x9F\x88\x81')
    SQUARED_KATAKANA_SA = n(b'\xF0\x9F\x88\x82')
@@ -62,13 +62,11 @@ class TelegramError(Exception):


 class Unauthorized(TelegramError):
-
    def __init__(self):
        super(Unauthorized, self).__init__('Unauthorized')


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

@@ -78,6 +76,5 @@ class NetworkError(TelegramError):


 class TimedOut(NetworkError):
-
    def __init__(self):
        super(TimedOut, self).__init__('Timed out')
@@ -22,5 +22,18 @@
 from .dispatcher import Dispatcher
 from .jobqueue import JobQueue
 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, Filters
+from .regexhandler import RegexHandler
+from .stringcommandhandler import StringCommandHandler
+from .stringregexhandler import StringRegexHandler
+from .typehandler import TypeHandler

-__all__ = ('Dispatcher', 'JobQueue', 'Updater')
+__all__ = ('Dispatcher', 'JobQueue', 'Updater', 'CallbackQueryHandler',
+           'ChosenInlineResultHandler', 'CommandHandler', 'Handler',
+           'InlineQueryHandler', 'MessageHandler', 'Filters', 'RegexHandler',
+           'StringCommandHandler', 'StringRegexHandler', 'TypeHandler')
@@ -0,0 +1,48 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 CallbackQueryHandler class """
+
+from .handler import Handler
+from telegram import Update
+
+
+class CallbackQueryHandler(Handler):
+    """
+    Handler class to handle Telegram callback queries.
+
+    Args:
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``checkUpdate``
+            has determined that an update should be processed by this handler.
+        pass_update_queue (optional[bool]): If the handler should be passed the
+            update queue as a keyword argument called ``update_queue``. It can
+            be used to insert updates. Default is ``False``
+    """
+
+    def __init__(self, callback, pass_update_queue=False):
+        super(CallbackQueryHandler, self).__init__(callback, pass_update_queue)
+
+    def checkUpdate(self, update):
+        return isinstance(update, Update) and update.callback_query
+
+    def handleUpdate(self, update, dispatcher):
+        optional_args = self.collectOptionalArgs(dispatcher)
+
+        self.callback(dispatcher.bot, update, **optional_args)
@@ -0,0 +1,50 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 ChosenInlineResultHandler class """
+
+from .handler import Handler
+from telegram import Update
+
+
+class ChosenInlineResultHandler(Handler):
+    """
+    Handler class to handle Telegram updates that contain a chosen inline
+    result.
+
+    Args:
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``checkUpdate``
+            has determined that an update should be processed by this handler.
+        pass_update_queue (optional[bool]): If the handler should be passed the
+            update queue as a keyword argument called ``update_queue``. It can
+            be used to insert updates. Default is ``False``
+    """
+
+    def __init__(self, callback, pass_update_queue=False):
+        super(ChosenInlineResultHandler, self).__init__(callback,
+                                                        pass_update_queue)
+
+    def checkUpdate(self, update):
+        return isinstance(update, Update) and update.chosen_inline_result
+
+    def handleUpdate(self, update, dispatcher):
+        optional_args = self.collectOptionalArgs(dispatcher)
+
+        self.callback(dispatcher.bot, update, **optional_args)
@@ -0,0 +1,66 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 CommandHandler class """
+
+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.
+
+    Args:
+        command (str): The name of the command this handler should listen for.
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``checkUpdate``
+            has determined that an update should be processed by this handler.
+        pass_args (optional[bool]): If 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 spaces. Default is ``False``
+        pass_update_queue (optional[bool]): If the handler should be passed the
+            update queue as a keyword argument called ``update_queue``. It can
+            be used to insert updates. Default is ``False``
+    """
+
+    def __init__(self, command, callback, pass_args=False,
+                 pass_update_queue=False):
+        super(CommandHandler, self).__init__(callback, pass_update_queue)
+        self.command = command
+        self.pass_args = pass_args
+
+    def checkUpdate(self, update):
+        return (isinstance(update, Update) and
+                update.message and
+                update.message.text and
+                update.message.text.startswith('/') and
+                update.message.text[1:].split(' ')[0].split('@')[0] ==
+                self.command)
+
+    def handleUpdate(self, update, dispatcher):
+        optional_args = self.collectOptionalArgs(dispatcher)
+
+        if self.pass_args:
+            optional_args['args'] = update.message.text.split(' ')[1:]
+
+        self.callback(dispatcher.bot, update, **optional_args)
@@ -21,13 +21,13 @@

 import logging
 from functools import wraps
-from inspect import getargspec
 from threading import Thread, BoundedSemaphore, Lock, Event, current_thread
-from re import match, split
 from time import sleep

-from telegram import (TelegramError, Update, NullHandler)
-from telegram.utils.updatequeue import Empty
+from queue import Empty
+
+from telegram import (TelegramError, NullHandler)
+from telegram.ext.handler import Handler

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

@@ -35,13 +35,12 @@ semaphore = None
 async_threads = set()
 """:type: set[Thread]"""
 async_lock = Lock()
+DEFAULT_GROUP = 0


 def run_async(func):
    """
-    Function decorator that will run the function in a new thread. A function
-    decorated with this will have to include **kwargs in their parameter list,
-    which will contain all optional parameters.
+    Function decorator that will run the function in a new thread.

    Args:
        func (function): The function to run in the thread.
@@ -58,10 +57,13 @@ def run_async(func):
        """
        A wrapper to run a thread in a thread pool
        """
-        result = func(*pargs, **kwargs)
-        semaphore.release()
-        with async_lock:
-            async_threads.remove(current_thread())
+        try:
+            result = func(*pargs, **kwargs)
+        finally:
+            semaphore.release()
+
+            with async_lock:
+                async_threads.remove(current_thread())
        return result

    @wraps(func)
@@ -79,75 +81,26 @@ def run_async(func):
    return async_func


-class Dispatcher:
+class Dispatcher(object):
    """
    This class dispatches all kinds of updates to its registered handlers.
-    A handler is a function that usually takes the following parameters
-
-        bot:
-            The telegram.Bot instance that received the message
-        update:
-            The update that should be handled by the handler
-
-    Error handlers take an additional parameter
-
-        error:
-            The TelegramError instance that was raised during processing the
-            update
-
-    All handlers, except error handlers, can also request more information by
-    appending one or more of the following arguments in their argument list for
-    convenience
-
-        update_queue:
-            The Queue instance which contains all new updates and is
-            processed by the Dispatcher. Be careful with this - you might
-            create an infinite loop.
-        args:
-            If the update is an instance str or telegram.Update, this will be
-            a list that contains the content of the message split on spaces,
-            except the first word (usually the command).
-            Example: '/add item1 item2 item3' -> ['item1', 'item2', 'item3']
-            For updates that contain inline queries, they will contain the
-            whole query split on spaces.
-            For other updates, args will be None
-
-    In some cases handlers may need some context data to process the update. To
-    procedure just queue in  update_queue.put(update, context=context) or
-    processUpdate(update,context=context).
-
-        context:
-            Extra data for handling updates.
-
-    For regex-based handlers, you can also request information about the match.
-    For all other handlers, these will be None
-
-        groups:
-            A tuple that contains the result of
-            re.match(matcher, ...).groups()
-        groupdict:
-            A dictionary that contains the result of
-            re.match(matcher, ...).groupdict()

    Args:
        bot (telegram.Bot): The bot object that should be passed to the
            handlers
-        update_queue (telegram.UpdateQueue): The synchronized queue that will
-            contain the updates.
+        update_queue (Queue): The synchronized queue that will contain the
+            updates.
    """
    def __init__(self, bot, update_queue, workers=4, exception_event=None):
        self.bot = bot
        self.update_queue = update_queue
-        self.telegram_message_handlers = []
-        self.telegram_inline_handlers = []
-        self.telegram_command_handlers = {}
-        self.telegram_regex_handlers = {}
-        self.string_regex_handlers = {}
-        self.string_command_handlers = {}
-        self.type_handlers = {}
-        self.unknown_telegram_command_handlers = []
-        self.unknown_string_command_handlers = []
+
+        self.handlers = {}
+        """:type: dict[int, list[Handler]"""
+        self.groups = []
+        """:type: list[int]"""
        self.error_handlers = []
+
        self.logger = logging.getLogger(__name__)
        self.running = False
        self.__stop_event = Event()
@@ -177,40 +130,22 @@ class Dispatcher:
        self.running = True
        self.logger.debug('Dispatcher started')

-        while 1:
+        while True:
            try:
                # Pop update from update queue.
-                update, context = self.update_queue.get(True, 1, True)
+                update = self.update_queue.get(True, 1)
            except Empty:
                if self.__stop_event.is_set():
                    self.logger.debug('orderly stopping')
                    break
-                elif self.__stop_event.is_set():
+                elif self.__exception_event.is_set():
                    self.logger.critical(
                        'stopping due to exception in another thread')
                    break
                continue

-            try:
-                self.processUpdate(update, context)
-                self.logger.debug('Processed Update: %s with context %s'
-                                  % (update, context))
-
-            # Dispatch any errors
-            except TelegramError as te:
-                self.logger.warn("Error was raised while processing Update.")
-
-                try:
-                    self.dispatchError(update, te)
-                # Log errors in error handlers
-                except:
-                    self.logger.exception("An uncaught error was raised while "
-                                          "handling the error")
-
-            # All other errors should not stop the thread, just print them
-            except:
-                self.logger.exception("An uncaught error was raised while "
-                                      "processing an update")
+            self.logger.debug('Processing Update: %s' % update)
+            self.processUpdate(update)

        self.running = False
        self.logger.debug('Dispatcher thread stopped')
@@ -225,481 +160,129 @@ class Dispatcher:
                sleep(0.1)
            self.__stop_event.clear()

-    def processUpdate(self, update, context=None):
+    def processUpdate(self, update):
        """
        Processes a single update.

        Args:
-            update (any):
+            update (object):
        """

-        handled = False
-
-        # Custom type handlers
-        for t in self.type_handlers:
-            if isinstance(update, t):
-                self.dispatchType(update, context)
-                handled = True
-
-        # string update
-        if type(update) is str and update.startswith('/'):
-            self.dispatchStringCommand(update, context)
-            handled = True
-        elif type(update) is str:
-            self.dispatchRegex(update, context)
-            handled = True
-
        # An error happened while polling
        if isinstance(update, TelegramError):
            self.dispatchError(None, update)
-            handled = True

-        # Telegram update (regex)
-        if isinstance(update, Update) and update.message is not None:
-            self.dispatchRegex(update, context)
-            handled = True
+        else:
+            for group in self.groups:
+                for handler in self.handlers[group]:
+                    try:
+                        if handler.checkUpdate(update):
+                            handler.handleUpdate(update, self)
+                            break
+                    # Dispatch any errors
+                    except TelegramError as te:
+                        self.logger.warn(
+                            'A TelegramError was raised while processing the '
+                            'Update.')

-            # Telegram update (command)
-            if update.message.text.startswith('/'):
-                self.dispatchTelegramCommand(update, context)
+                        try:
+                            self.dispatchError(update, te)
+                        except Exception:
+                            self.logger.exception(
+                                'An uncaught error was raised while '
+                                'handling the error')
+                        finally:
+                            break

-            # Telegram update (message)
-            else:
-                self.dispatchTelegramMessage(update, context)
-                handled = True
-        elif isinstance(update, Update) and \
-                (update.inline_query is not None or
-                 update.chosen_inline_result is not None):
-                self.dispatchTelegramInline(update, context)
-                handled = True
-        # Update not recognized
-        if not handled:
-            self.dispatchError(update, TelegramError(
-                "Received update of unknown type %s" % type(update)))
+                    # Errors should not stop the thread
+                    except Exception:
+                        self.logger.exception(
+                            'An uncaught error was raised while '
+                            'processing the update')
+                        break

-    # Add Handlers
-    def addTelegramMessageHandler(self, handler):
+    def addHandler(self, handler, group=DEFAULT_GROUP):
        """
-        Registers a message handler in the Dispatcher.
+        Register a handler.
+
+        TL;DR: Order and priority counts. 0 or 1 handlers per group will be
+        used.
+
+        A handler must be an instance of a subclass of
+        telegram.ext.Handler. All handlers are organized in groups with a
+        numeric value. The default group is 0. All groups will be evaluated for
+        handling an update, but only 0 or 1 handler per group will be used.
+
+        The priority/order of handlers is determined as follows:
+
+          * Priority of the group (lower group number == higher priority)
+
+          * The first handler in a group which should handle an update will be
+            used. Other handlers from the group will not be used. The order in
+            which handlers were added to the group defines the priority.

        Args:
-            handler (function): A function that takes (Bot, Update, *args) as
-                arguments.
+            handler (Handler): A Handler instance
+            group (Optional[int]): The group identifier. Default is 0
        """

-        self.telegram_message_handlers.append(handler)
+        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')

-    def addTelegramInlineHandler(self, handler):
+        if group not in self.handlers:
+            self.handlers[group] = list()
+            self.groups.append(group)
+            self.groups = sorted(self.groups)
+
+        self.handlers[group].append(handler)
+
+    def removeHandler(self, handler, group=DEFAULT_GROUP):
        """
-        Registers an inline query handler in the Dispatcher.
+        Remove a handler from the specified group

        Args:
-            handler (function): A function that takes (Bot, Update, *args) as
-                arguments.
+            handler (Handler): A Handler instance
+            group (optional[object]): The group identifier. Default is 0
        """
+        if handler in self.handlers[group]:
+            self.handlers[group].remove(handler)
+            if not self.handlers[group]:
+                del self.handlers[group]
+                self.groups.remove(group)

-        self.telegram_inline_handlers.append(handler)
-
-    def addTelegramCommandHandler(self, command, handler):
-        """
-        Registers a command handler in the Dispatcher.
-
-        Args:
-            command (str): The command keyword that this handler should be
-                listening to.
-            handler (function): A function that takes (Bot, Update, *args) as
-                arguments.
-        """
-
-        if command not in self.telegram_command_handlers:
-            self.telegram_command_handlers[command] = []
-
-        self.telegram_command_handlers[command].append(handler)
-
-    def addTelegramRegexHandler(self, matcher, handler):
-        """
-        Registers a regex handler in the Dispatcher. If handlers will be
-        called if re.match(matcher, update.message.text) is True.
-
-        Args:
-            matcher (str/__Regex): A regex string or compiled regex object that
-                matches on messages that handler should be listening to
-            handler (function): A function that takes (Bot, Update, *args) as
-                arguments.
-        """
-
-        if matcher not in self.telegram_regex_handlers:
-            self.telegram_regex_handlers[matcher] = []
-
-        self.telegram_regex_handlers[matcher].append(handler)
-
-    def addStringCommandHandler(self, command, handler):
-        """
-        Registers a string-command handler in the Dispatcher.
-
-        Args:
-            command (str): The command keyword that this handler should be
-                listening to.
-            handler (function): A function that takes (Bot, str, *args) as
-                arguments.
-        """
-
-        if command not in self.string_command_handlers:
-            self.string_command_handlers[command] = []
-
-        self.string_command_handlers[command].append(handler)
-
-    def addStringRegexHandler(self, matcher, handler):
-        """
-        Registers a regex handler in the Dispatcher. If handlers will be
-        called if re.match(matcher, string) is True.
-
-        Args:
-            matcher (str/__Regex): A regex string or compiled regex object that
-                matches on the string input that handler should be listening to
-            handler (function): A function that takes (Bot, Update, *args) as
-                arguments.
-        """
-
-        if matcher not in self.string_regex_handlers:
-            self.string_regex_handlers[matcher] = []
-
-        self.string_regex_handlers[matcher].append(handler)
-
-    def addUnknownTelegramCommandHandler(self, handler):
-        """
-        Registers a command handler in the Dispatcher, that will receive all
-        commands that have no associated handler.
-
-        Args:
-            handler (function): A function that takes (Bot, Update, *args) as
-                arguments.
-        """
-
-        self.unknown_telegram_command_handlers.append(handler)
-
-    def addUnknownStringCommandHandler(self, handler):
-        """
-        Registers a string-command handler in the Dispatcher, that will
-        receive all commands that have no associated handler.
-
-        Args:
-            handler (function): A function that takes (Bot, str, *args) as
-                arguments.
-        """
-
-        self.unknown_string_command_handlers.append(handler)
-
-    def addErrorHandler(self, handler):
+    def addErrorHandler(self, callback):
        """
        Registers an error handler in the Dispatcher.

        Args:
-            handler (function): A function that takes (Bot, TelegramError) as
-                arguments.
+            handler (function): A function that takes ``Bot, Update,
+                TelegramError`` as arguments.
        """

-        self.error_handlers.append(handler)
+        self.error_handlers.append(callback)

-    def addTypeHandler(self, the_type, handler):
-        """
-        Registers a type handler in the Dispatcher. This allows you to send
-        any type of object into the update queue.
-
-        Args:
-            the_type (type): The type this handler should listen to
-            handler (function): A function that takes (Bot, type, *args) as
-                arguments.
-        """
-
-        if the_type not in self.type_handlers:
-            self.type_handlers[the_type] = []
-
-        self.type_handlers[the_type].append(handler)
-
-    # Remove Handlers
-    def removeTelegramMessageHandler(self, handler):
-        """
-        De-registers a message handler.
-
-        Args:
-            handler (any):
-        """
-
-        if handler in self.telegram_message_handlers:
-            self.telegram_message_handlers.remove(handler)
-
-    def removeTelegramInlineHandler(self, handler):
-        """
-        De-registers an inline query handler.
-
-        Args:
-            handler (any):
-        """
-
-        if handler in self.telegram_inline_handlers:
-            self.telegram_inline_handlers.remove(handler)
-
-    def removeTelegramCommandHandler(self, command, handler):
-        """
-        De-registers a command handler.
-
-        Args:
-            command (str): The command
-            handler (any):
-        """
-
-        if command in self.telegram_command_handlers \
-                and handler in self.telegram_command_handlers[command]:
-            self.telegram_command_handlers[command].remove(handler)
-
-    def removeTelegramRegexHandler(self, matcher, handler):
-        """
-        De-registers a regex handler.
-
-        Args:
-            matcher (str/__Regex): The regex matcher object or string
-            handler (any):
-        """
-
-        if matcher in self.telegram_regex_handlers \
-                and handler in self.telegram_regex_handlers[matcher]:
-            self.telegram_regex_handlers[matcher].remove(handler)
-
-    def removeStringCommandHandler(self, command, handler):
-        """
-        De-registers a string-command handler.
-
-        Args:
-            command (str): The command
-            handler (any):
-        """
-
-        if command in self.string_command_handlers \
-                and handler in self.string_command_handlers[command]:
-            self.string_command_handlers[command].remove(handler)
-
-    def removeStringRegexHandler(self, matcher, handler):
-        """
-        De-registers a regex handler.
-
-        Args:
-            matcher (str/__Regex): The regex matcher object or string
-            handler (any):
-        """
-
-        if matcher in self.string_regex_handlers \
-                and handler in self.string_regex_handlers[matcher]:
-            self.string_regex_handlers[matcher].remove(handler)
-
-    def removeUnknownTelegramCommandHandler(self, handler):
-        """
-        De-registers an unknown-command handler.
-
-        Args:
-            handler (any):
-        """
-
-        if handler in self.unknown_telegram_command_handlers:
-            self.unknown_telegram_command_handlers.remove(handler)
-
-    def removeUnknownStringCommandHandler(self, handler):
-        """
-        De-registers an unknown-command handler.
-
-        Args:
-            handler (any):
-        """
-
-        if handler in self.unknown_string_command_handlers:
-            self.unknown_string_command_handlers.remove(handler)
-
-    def removeErrorHandler(self, handler):
+    def removeErrorHandler(self, callback):
        """
        De-registers an error handler.

        Args:
-            handler (any):
+            handler (function):
        """

-        if handler in self.error_handlers:
-            self.error_handlers.remove(handler)
-
-    def removeTypeHandler(self, the_type, handler):
-        """
-        De-registers a type handler.
-
-        Args:
-            handler (any):
-        """
-
-        if the_type in self.type_handlers \
-                and handler in self.type_handlers[the_type]:
-            self.type_handlers[the_type].remove(handler)
-
-    def dispatchTelegramCommand(self, update, context=None):
-        """
-        Dispatches an update that contains a command.
-
-        Args:
-            command (str): The command keyword
-            update (telegram.Update): The Telegram update that contains the
-                command
-        """
-
-        command = split('\W', update.message.text[1:])[0]
-
-        if command in self.telegram_command_handlers:
-            self.dispatchTo(self.telegram_command_handlers[command], update,
-                            context=context)
-        else:
-            self.dispatchTo(self.unknown_telegram_command_handlers, update,
-                            context=context)
-
-    def dispatchRegex(self, update, context=None):
-        """
-        Dispatches an update to all string or telegram regex handlers that
-        match the string/message content.
-
-        Args:
-            update (str, Update): The update that should be checked for matches
-        """
-
-        if isinstance(update, Update):
-            handlers = self.telegram_regex_handlers
-            to_match = update.message.text
-        elif isinstance(update, str):
-            handlers = self.string_regex_handlers
-            to_match = update
-
-        for matcher in handlers:
-            m = match(matcher, to_match)
-            if m:
-                for handler in handlers[matcher]:
-                    self.call_handler(handler,
-                                      update,
-                                      groups=m.groups(),
-                                      groupdict=m.groupdict(),
-                                      context=context)
-
-    def dispatchStringCommand(self, update, context=None):
-        """
-        Dispatches a string-update that contains a command.
-
-        Args:
-            update (str): The string input
-        """
-
-        command = update.split(' ')[0][1:]
-
-        if command in self.string_command_handlers:
-            self.dispatchTo(self.string_command_handlers[command], update,
-                            context=context)
-        else:
-            self.dispatchTo(self.unknown_string_command_handlers, update,
-                            context=context)
-
-    def dispatchType(self, update, context=None):
-        """
-        Dispatches an update of any type.
-
-        Args:
-            update (any): The update
-        """
-
-        for t in self.type_handlers:
-            if isinstance(update, t):
-                self.dispatchTo(self.type_handlers[t], update, context=context)
-
-    def dispatchTelegramMessage(self, update, context=None):
-        """
-        Dispatches an update that contains a regular message.
-
-        Args:
-            update (telegram.Update): The Telegram update that contains the
-                message.
-        """
-
-        self.dispatchTo(self.telegram_message_handlers, update,
-                        context=context)
-
-    def dispatchTelegramInline(self, update, context=None):
-        """
-        Dispatches an update that contains an inline update.
-
-        Args:
-            update (telegram.Update): The Telegram update that contains the
-                message.
-        """
-
-        self.dispatchTo(self.telegram_inline_handlers, update, context=None)
+        if callback in self.error_handlers:
+            self.error_handlers.remove(callback)

    def dispatchError(self, update, error):
        """
        Dispatches an error.

        Args:
-            update (any): The pdate that caused the error
+            update (object): The update that caused the error
            error (telegram.TelegramError): The Telegram error that was raised.
        """

-        for handler in self.error_handlers:
-            handler(self.bot, update, error)
-
-    def dispatchTo(self, handlers, update, **kwargs):
-        """
-        Dispatches an update to a list of handlers.
-
-        Args:
-            handlers (list): A list of handler-functions.
-            update (any): The update to be dispatched
-        """
-
-        for handler in handlers:
-            self.call_handler(handler, update, **kwargs)
-
-    def call_handler(self, handler, update, **kwargs):
-        """
-        Calls an update handler. Checks the handler for keyword arguments and
-        fills them, if possible.
-
-        Args:
-            handler (function): An update handler function
-            update (any): An update
-        """
-
-        target_kwargs = {}
-        fargs = getargspec(handler).args
-
-        '''
-        async handlers will receive all optional arguments, since we can't
-        their argument list.
-        '''
-
-        is_async = 'pargs' == getargspec(handler).varargs
-
-        if is_async or 'update_queue' in fargs:
-            target_kwargs['update_queue'] = self.update_queue
-
-        if is_async or 'args' in fargs:
-            if isinstance(update, Update) and update.message:
-                args = update.message.text.split(' ')[1:]
-            elif isinstance(update, Update) and update.inline_query:
-                args = update.inline_query.query.split(' ')
-            elif isinstance(update, str):
-                args = update.split(' ')[1:]
-            else:
-                args = None
-
-            target_kwargs['args'] = args
-
-        if is_async or 'groups' in fargs:
-            target_kwargs['groups'] = kwargs.get('groups', None)
-
-        if is_async or 'groupdict' in fargs:
-            target_kwargs['groupdict'] = kwargs.get('groupdict', None)
-
-        if is_async or 'context' in fargs:
-            target_kwargs['context'] = kwargs.get('context', None)
-
-        handler(self.bot, update, **target_kwargs)
+        for callback in self.error_handlers:
+            callback(self.bot, update, error)
@@ -0,0 +1,80 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 base class for handlers as used by the
+Dispatcher """
+
+
+class Handler(object):
+    """
+    The base class for all update handlers. You can create your own handlers
+    by inheriting from this class.
+
+    Args:
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``checkUpdate``
+            has determined that an update should be processed by this handler.
+        pass_update_queue (optional[bool]): If the callback should be passed
+            the update queue as a keyword argument called ``update_queue``. It
+            can be used to insert updates. Default is ``False``
+    """
+
+    def __init__(self, callback, pass_update_queue=False):
+        self.callback = callback
+        self.pass_update_queue = pass_update_queue
+
+    def checkUpdate(self, update):
+        """
+        This method is called to determine if an update should be handled by
+        this handler instance. It should always be overridden.
+
+        Args:
+            update (object): The update to be tested
+
+        Returns:
+            bool
+        """
+        raise NotImplementedError
+
+    def handleUpdate(self, update, dispatcher):
+        """
+        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.
+
+        Args:
+            update (object): The update to be handled
+
+        """
+        raise NotImplementedError
+
+    def collectOptionalArgs(self, dispatcher):
+        """
+        Prepares the optional arguments that are the same for all types of
+        handlers
+
+        Args:
+            dispatcher (Dispatcher):
+        """
+        optional_args = dict()
+        if self.pass_update_queue:
+            optional_args['update_queue'] = dispatcher.update_queue
+
+        return optional_args
@@ -0,0 +1,48 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 InlineQueryHandler class """
+
+from .handler import Handler
+from telegram import Update
+
+
+class InlineQueryHandler(Handler):
+    """
+    Handler class to handle Telegram inline queries.
+
+    Args:
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``checkUpdate``
+            has determined that an update should be processed by this handler.
+        pass_update_queue (optional[bool]): If the handler should be passed the
+            update queue as a keyword argument called ``update_queue``. It can
+            be used to insert updates. Default is ``False``
+    """
+
+    def __init__(self, callback, pass_update_queue=False):
+        super(InlineQueryHandler, self).__init__(callback, pass_update_queue)
+
+    def checkUpdate(self, update):
+        return isinstance(update, Update) and update.inline_query
+
+    def handleUpdate(self, update, dispatcher):
+        optional_args = self.collectOptionalArgs(dispatcher)
+
+        self.callback(dispatcher.bot, update, **optional_args)
@@ -22,11 +22,7 @@
 import logging
 import time
 from threading import Thread, Lock
-
-try:
-    from queue import PriorityQueue
-except ImportError:
-    from Queue import PriorityQueue
+from queue import PriorityQueue


 class JobQueue(object):
@@ -0,0 +1,130 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 MessageHandler class """
+
+from .handler import Handler
+from telegram import Update
+
+
+class Filters(object):
+    """
+    Convenient namespace (class) & methods for the filter funcs of the
+    MessageHandler class.
+    """
+
+    @staticmethod
+    def text(update):
+        return update.message.text and not update.message.text.startswith('/')
+
+    @staticmethod
+    def command(update):
+        return update.message.text and update.message.text.startswith('/')
+
+    @staticmethod
+    def audio(update):
+        return bool(update.message.audio)
+
+    @staticmethod
+    def document(update):
+        return bool(update.message.document)
+
+    @staticmethod
+    def photo(update):
+        return bool(update.message.photo)
+
+    @staticmethod
+    def sticker(update):
+        return bool(update.message.sticker)
+
+    @staticmethod
+    def video(update):
+        return bool(update.message.video)
+
+    @staticmethod
+    def voice(update):
+        return bool(update.message.voice)
+
+    @staticmethod
+    def contact(update):
+        return bool(update.message.contact)
+
+    @staticmethod
+    def location(update):
+        return bool(update.message.location)
+
+    @staticmethod
+    def venue(update):
+        return bool(update.message.venue)
+
+    @staticmethod
+    def status_update(update):
+        return bool(
+            update.message.new_chat_member or
+            update.message.left_chat_member or
+            update.message.new_chat_title or
+            update.message.new_chat_photo or
+            update.message.delete_chat_photo or
+            update.message.group_chat_created or
+            update.message.supergroup_chat_created or
+            update.message.channel_chat_created or
+            update.message.migrate_to_chat_id or
+            update.message.migrate_from_chat_id or
+            update.message.pinned_message)
+
+
+class MessageHandler(Handler):
+    """
+    Handler class to handle telegram messages. Messages are Telegram Updates
+    that do not contain a command. They might contain text, media or status
+    updates.
+
+    Args:
+        filters (list[function]): A list of filter functions. Standard filters
+            can be found in the Filters class above.
+          | Each `function` takes ``Update`` as arg and returns ``bool``.
+          | All messages that match at least one of those filters will be
+            accepted. If ``bool(filters)`` evaluates to ``False``, messages are
+            not filtered.
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``checkUpdate``
+            has determined that an update should be processed by this handler.
+        pass_update_queue (optional[bool]): If the handler should be passed the
+            update queue as a keyword argument called ``update_queue``. It can
+            be used to insert updates. Default is ``False``
+    """
+
+    def __init__(self, filters, callback, pass_update_queue=False):
+        super(MessageHandler, self).__init__(callback, pass_update_queue)
+        self.filters = filters
+
+    def checkUpdate(self, update):
+        if isinstance(update, Update) and update.message:
+            if not self.filters:
+                res = True
+            else:
+                res = any(func(update) for func in self.filters)
+        else:
+            res = False
+        return res
+
+    def handleUpdate(self, update, dispatcher):
+        optional_args = self.collectOptionalArgs(dispatcher)
+
+        self.callback(dispatcher.bot, update, **optional_args)
@@ -0,0 +1,82 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 RegexHandler class """
+
+import re
+
+from future.utils import string_types
+
+from .handler import Handler
+from telegram import Update
+
+
+class RegexHandler(Handler):
+    """
+    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`` module for more information. The ``re.match`` function is used to
+    determine if an update should be handled by this handler.
+
+    Args:
+        pattern (str or Pattern): The regex pattern.
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``checkUpdate``
+            has determined that an update should be processed by this handler.
+        pass_groups (optional[bool]): If the callback should be passed the
+            result of ``re.match(pattern, text).groups()`` as a keyword
+            argument called ``groups``. Default is ``False``
+        pass_groupdict (optional[bool]): If the callback should be passed the
+            result of ``re.match(pattern, text).groupdict()`` as a keyword
+            argument called ``groupdict``. Default is ``False``
+        pass_update_queue (optional[bool]): If the handler should be passed the
+            update queue as a keyword argument called ``update_queue``. It can
+            be used to insert updates. Default is ``False``
+    """
+
+    def __init__(self, pattern, callback, pass_groups=False,
+                 pass_groupdict=False, pass_update_queue=False):
+        super(RegexHandler, self).__init__(callback, pass_update_queue)
+
+        if isinstance(pattern, string_types):
+            pattern = re.compile(pattern)
+
+        self.pattern = pattern
+        self.pass_groups = pass_groups
+        self.pass_groupdict = pass_groupdict
+
+    def checkUpdate(self, update):
+        if (isinstance(update, Update) and
+                update.message and
+                update.message.text):
+            match = re.match(self.pattern, update.message.text)
+            return bool(match)
+        else:
+            return False
+
+    def handleUpdate(self, update, dispatcher):
+        optional_args = self.collectOptionalArgs(dispatcher)
+        match = re.match(self.pattern, update.message.text)
+
+        if self.pass_groups:
+            optional_args['groups'] = match.groups()
+        if self.pass_groupdict:
+            optional_args['groupdict'] = match.groupdict()
+
+        self.callback(dispatcher.bot, update, **optional_args)
@@ -0,0 +1,61 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 StringCommandHandler class """
+
+from .handler import Handler
+
+
+class StringCommandHandler(Handler):
+    """
+    Handler class to handle string commands. Commands are string updates
+    that start with ``/``.
+
+    Args:
+        command (str): The name of the command this handler should listen for.
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``checkUpdate``
+            has determined that an update should be processed by this handler.
+        pass_args (optional[bool]): If 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 spaces. Default is ``False``
+        pass_update_queue (optional[bool]): If the handler should be passed the
+            update queue as a keyword argument called ``update_queue``. It can
+            be used to insert updates. Default is ``False``
+    """
+
+    def __init__(self, command, callback, pass_args=False,
+                 pass_update_queue=False):
+        super(StringCommandHandler, self).__init__(callback, pass_update_queue)
+        self.command = command
+        self.pass_args = pass_args
+
+    def checkUpdate(self, update):
+        return (isinstance(update, str) and
+                update.startswith('/') and
+                update[1:].split(' ')[0] == self.command)
+
+    def handleUpdate(self, update, dispatcher):
+        optional_args = self.collectOptionalArgs(dispatcher)
+
+        if self.pass_args:
+            optional_args['args'] = update.split(' ')[1:]
+
+        self.callback(dispatcher.bot, update, **optional_args)
@@ -0,0 +1,76 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 StringRegexHandler class """
+
+import re
+
+from future.utils import string_types
+
+from .handler import Handler
+
+
+class StringRegexHandler(Handler):
+    """
+    Handler class to handle string updates based on a regex. It uses a
+    regular expression to check update content. Read the documentation of the
+    ``re`` module for more information. The ``re.match`` function is used to
+    determine if an update should be handled by this handler.
+
+    Args:
+        pattern (str or Pattern): The regex pattern.
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``checkUpdate``
+            has determined that an update should be processed by this handler.
+        pass_groups (optional[bool]): If the callback should be passed the
+            result of ``re.match(pattern, update).groups()`` as a keyword
+            argument called ``groups``. Default is ``False``
+        pass_groupdict (optional[bool]): If the callback should be passed the
+            result of ``re.match(pattern, update).groupdict()`` as a keyword
+            argument called ``groupdict``. Default is ``False``
+        pass_update_queue (optional[bool]): If the handler should be passed the
+            update queue as a keyword argument called ``update_queue``. It can
+            be used to insert updates. Default is ``False``
+    """
+
+    def __init__(self, pattern, callback, pass_groups=False,
+                 pass_groupdict=False, pass_update_queue=False):
+        super(StringRegexHandler, self).__init__(callback, pass_update_queue)
+
+        if isinstance(pattern, string_types):
+            pattern = re.compile(pattern)
+
+        self.pattern = pattern
+        self.pass_groups = pass_groups
+        self.pass_groupdict = pass_groupdict
+
+    def checkUpdate(self, update):
+        return isinstance(update, string_types) and bool(
+            re.match(self.pattern, update))
+
+    def handleUpdate(self, update, dispatcher):
+        optional_args = self.collectOptionalArgs(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()
+
+        self.callback(dispatcher.bot, update, **optional_args)
@@ -0,0 +1,56 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 TypeHandler class """
+
+from .handler import Handler
+
+
+class TypeHandler(Handler):
+    """
+    Handler class to handle updates of custom types.
+
+    Args:
+        type (type): The ``type`` of updates this handler should process, as
+            determined by ``isinstance``
+        callback (function): A function that takes ``bot, update`` as
+            positional arguments. It will be called when the ``checkUpdate``
+            has determined that an update should be processed by this handler.
+        strict (optional[bool]): Use ``type`` instead of ``isinstance``.
+            Default is ``False``
+        pass_update_queue (optional[bool]): If the handler should be passed the
+            update queue as a keyword argument called ``update_queue``. It can
+            be used to insert updates. Default is ``False``
+    """
+
+    def __init__(self, type, callback, strict=False, pass_update_queue=False):
+        super(TypeHandler, self).__init__(callback, pass_update_queue)
+        self.type = type
+        self.strict = strict
+
+    def checkUpdate(self, update):
+        if not self.strict:
+            return isinstance(update, self.type)
+        else:
+            return type(update) is self.type
+
+    def handleUpdate(self, update, dispatcher):
+        optional_args = self.collectOptionalArgs(dispatcher)
+
+        self.callback(dispatcher.bot, update, **optional_args)
@@ -28,19 +28,20 @@ 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
+
 from telegram import Bot, TelegramError, NullHandler
 from telegram.ext import dispatcher, Dispatcher, JobQueue
 from telegram.error import Unauthorized, InvalidToken
-from telegram.utils.updatequeue import UpdateQueue
 from telegram.utils.webhookhandler import (WebhookServer, WebhookHandler)

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


-class Updater:
+class Updater(object):
    """
    This class, which employs the Dispatcher class, provides a frontend to
-    telegram.Bot to the programmer, so they can focus on coding the bot. It's
+    telegram.Bot to the programmer, so they can focus on coding the bot. Its
    purpose is to receive the updates from Telegram and to deliver them to said
    dispatcher. It also runs in a separate thread, so the user can interact
    with the bot, for example on the command line. The dispatcher supports
@@ -81,7 +82,7 @@ class Updater:
            self.bot = bot
        else:
            self.bot = Bot(token, base_url)
-        self.update_queue = UpdateQueue()
+        self.update_queue = Queue()
        self.job_queue = JobQueue(self.bot, job_queue_tick_interval)
        self.__exception_event = Event()
        self.dispatcher = Dispatcher(self.bot, self.update_queue, workers,
@@ -110,9 +111,10 @@ class Updater:
                False.
            bootstrap_retries (Optional[int[): Whether the bootstrapping phase
                of the `Updater` will retry on failures on the Telegram server.
-                < 0 - retry indefinitely
-                  0 - no retries (default)
-                > 0 - retry up to X times
+
+                |   < 0 - retry indefinitely
+                |   0 - no retries (default)
+                |   > 0 - retry up to X times

        Returns:
            Queue: The update queue that can be filled from the main thread
@@ -177,9 +179,10 @@ class Updater:
                is False.
            bootstrap_retries (Optional[int[): Whether the bootstrapping phase
                of the `Updater` will retry on failures on the Telegram server.
-                < 0 - retry indefinitely
-                  0 - no retries (default)
-                > 0 - retry up to X times
+
+                |   < 0 - retry indefinitely
+                |   0 - no retries (default)
+                |   > 0 - retry up to X times
            webhook_url (Optional[str]): Explicitly specifiy the webhook url.
                Useful behind NAT, reverse proxy, etc. Default is derived from
                `listen`, `port` & `url_path`.
@@ -214,7 +217,7 @@ class Updater:
        cur_interval = poll_interval
        self.logger.debug('Updater thread started')

-        self._set_webhook(None, bootstrap_retries)
+        self._set_webhook(None, bootstrap_retries, None)

        while self.running:
            try:
@@ -246,12 +249,13 @@ class Updater:

            sleep(cur_interval)

-    def _set_webhook(self, webhook_url, max_retries):
+    def _set_webhook(self, webhook_url, max_retries, cert):
        retries = 0
        while 1:
            try:
                # Remove webhook
-                self.bot.setWebhook(webhook_url=webhook_url)
+                self.bot.setWebhook(webhook_url=webhook_url,
+                                    certificate=cert)
            except (Unauthorized, InvalidToken):
                raise
            except TelegramError:
@@ -282,43 +286,48 @@ class Updater:
                       bootstrap_retries, webhook_url):
        self.logger.debug('Updater thread started')
        use_ssl = cert is not None and key is not None
-        url_path = "/%s" % url_path
+        if not url_path.startswith('/'):
+            url_path = '/{0}'.format(url_path)

        # Create and start server
        self.httpd = WebhookServer((listen, port), WebhookHandler,
                                   self.update_queue, url_path)
-        if not webhook_url:
-            webhook_url = self._gen_webhook_url(listen, port, url_path,
-                                                use_ssl)
-        self._set_webhook(webhook_url, bootstrap_retries)

        if use_ssl:
-            # 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
+            self._check_ssl_cert(cert, key)

-            if exit_code is 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')
+            # 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)
+
+            self._set_webhook(webhook_url, bootstrap_retries,
+                              open(cert, 'rb'))

        self.httpd.serve_forever(poll_interval=1)

-    def _gen_webhook_url(self, listen, port, url_path, use_ssl):
-        return '{proto}://{listen}:{port}{path}'.format(
-            proto='https' if use_ssl else 'http',
+    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 is 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')
+
+    def _gen_webhook_url(self, listen, port, url_path):
+        return 'https://{listen}:{port}{path}'.format(
            listen=listen,
            port=port,
            path=url_path)
@@ -383,7 +392,12 @@ class Updater:

    def signal_handler(self, signum, frame):
        self.is_idle = False
-        self.stop()
+        if self.running:
+            self.stop()
+        else:
+            self.logger.warning('Exiting immediately!')
+            import os
+            os._exit(1)

    def idle(self, stop_signals=(SIGINT, SIGTERM, SIGABRT)):
        """
@@ -26,7 +26,6 @@ from telegram.utils.request import download as _download


 class File(TelegramObject):
-
    """This object represents a Telegram File.

    Attributes:
@@ -0,0 +1,76 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 a object that represents a Telegram
+InlineKeyboardButton"""
+
+from telegram import TelegramObject
+
+
+class InlineKeyboardButton(TelegramObject):
+    """This object represents a Telegram InlineKeyboardButton.
+
+    Attributes:
+        text (str):
+        url (str):
+        callback_data (str):
+        switch_inline_query (str):
+
+    Args:
+        text (str):
+        **kwargs: Arbitrary keyword arguments.
+
+    Keyword Args:
+        url (Optional[str]):
+        callback_data (Optional[str]):
+        switch_inline_query (Optional[str]):
+
+    """
+
+    def __init__(self,
+                 text,
+                 **kwargs):
+        # Required
+        self.text = text
+
+        # Optionals
+        self.url = kwargs.get('url')
+        self.callback_data = kwargs.get('callback_data')
+        self.switch_inline_query = kwargs.get('switch_inline_query')
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineKeyboardButton, InlineKeyboardButton).de_json(data)
+
+        if not data:
+            return None
+
+        return InlineKeyboardButton(**data)
+
+    @staticmethod
+    def de_list(data):
+        if not data:
+            return []
+
+        inline_keyboards = list()
+        for inline_keyboard in data:
+            inline_keyboards.append(InlineKeyboardButton.
+                                    de_json(inline_keyboard))
+
+        return inline_keyboards
@@ -0,0 +1,63 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 a object that represents a Telegram
+InlineKeyboardMarkup"""
+
+from telegram import ReplyMarkup, InlineKeyboardButton
+
+
+class InlineKeyboardMarkup(ReplyMarkup):
+    """This object represents a Telegram InlineKeyboardMarkup.
+
+    Attributes:
+        inline_keyboard (List[List[:class:`telegram.InlineKeyboardMarkup`]]):
+
+    Args:
+        inline_keyboard (List[List[:class:`telegram.InlineKeyboardMarkup`]]):
+
+    """
+
+    def __init__(self,
+                 inline_keyboard):
+        # Required
+        self.inline_keyboard = inline_keyboard
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineKeyboardMarkup, InlineKeyboardMarkup).de_json(data)
+
+        if not data:
+            return None
+
+        data['inline_keyboard'] = \
+            [InlineKeyboardButton.de_list(inline_keyboard) for inline_keyboard
+             in data['inline_keyboard']]
+
+        return InlineKeyboardMarkup(**data)
+
+    def to_dict(self):
+        data = super(InlineKeyboardMarkup, self).to_dict()
+
+        data['inline_keyboard'] = []
+        for inline_keyboard in self.inline_keyboard:
+            data['inline_keyboard'].append(
+                [x.to_dict() for x in inline_keyboard])
+
+        return data
@@ -39,14 +39,14 @@ class InlineQuery(TelegramObject):
        from_user (:class:`telegram.User`):
        query (str):
        offset (str):
-
    """

    def __init__(self,
                 id,
                 from_user,
                 query,
-                 offset):
+                 offset,
+                 **kwargs):
        # Required
        self.id = id
        self.from_user = from_user
@@ -62,10 +62,12 @@ class InlineQuery(TelegramObject):
        Returns:
            telegram.InlineQuery:
        """
+        data = super(InlineQuery, InlineQuery).de_json(data)
+
        if not data:
            return None
-        data = data.copy()
-        data['from_user'] = User.de_json(data.pop('from'))
+
+        data['from_user'] = User.de_json(data.get('from'))

        return InlineQuery(**data)

@@ -1,7 +1,8 @@
 #!/usr/bin/env python
 #
 # A library that provides a Python interface to the Telegram Bot API
-# Copyright (C) 2015 Leandro Toledo de Souza <devs@python-telegram-bot.org>
+# Copyright (C) 2015-2016
+# 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
@@ -16,13 +17,10 @@
 # You should have received a copy of the GNU Lesser Public License
 # along with this program.  If not, see [http://www.gnu.org/licenses/].

-"""
-This module contains the classes that represent Telegram InlineQueryResults
-https://core.telegram.org/bots/api#inline-mode
-"""
+"""This module contains the classes that represent Telegram
+InlineQueryResult"""

 from telegram import TelegramObject
-from telegram.utils.validate import validate_string


 class InlineQueryResult(TelegramObject):
@@ -47,453 +45,4 @@ class InlineQueryResult(TelegramObject):

    @staticmethod
    def de_json(data):
-        """
-        Args:
-            data (dict):
-
-        Returns:
-            telegram.InlineQueryResult:
-        """
-        if not data:
-            return None
-
-        return InlineQueryResult(**data)
-
-
-class InlineQueryResultArticle(InlineQueryResult):
-    """This object represents a Telegram InlineQueryResultArticle.
-
-    Attributes:
-        id (str):
-        title (str):
-        message_text (str):
-        parse_mode (str):
-        disable_web_page_preview (bool):
-        url (str):
-        hide_url (bool):
-        description (str):
-        thumb_url (str):
-        thumb_width (int):
-        thumb_height (int):
-
-    Args:
-        id (str): Unique identifier for this result, 1-64 Bytes
-        title (str):
-        message_text (str):
-
-    Keyword Args:
-        parse_mode (Optional[str]):
-        disable_web_page_preview (Optional[bool]):
-        url (Optional[str]):
-        hide_url (Optional[bool]):
-        description (Optional[str]):
-        thumb_url (Optional[str]):
-        thumb_width (Optional[int]):
-        thumb_height (Optional[int]):
-    """
-
-    def __init__(self,
-                 id,
-                 title,
-                 message_text,
-                 parse_mode=None,
-                 disable_web_page_preview=None,
-                 url=None,
-                 hide_url=None,
-                 description=None,
-                 thumb_url=None,
-                 thumb_width=None,
-                 thumb_height=None):
-
-        validate_string(title, 'title')
-        validate_string(message_text, 'message_text')
-        validate_string(url, 'url')
-        validate_string(description, 'description')
-        validate_string(thumb_url, 'thumb_url')
-        validate_string(parse_mode, 'parse_mode')
-
-        # Required
-        super(InlineQueryResultArticle, self).__init__('article', id)
-        self.title = title
-        self.message_text = message_text
-
-        # Optional
-        self.parse_mode = parse_mode
-        self.disable_web_page_preview = bool(disable_web_page_preview)
-        self.url = url
-        self.hide_url = bool(hide_url)
-        self.description = description
-        self.thumb_url = thumb_url
-        if thumb_width is not None:
-            self.thumb_width = int(thumb_width)
-        if thumb_height is not None:
-            self.thumb_height = int(thumb_height)
-
-    @staticmethod
-    def de_json(data):
-        """
-        Args:
-            data (dict):
-
-        Returns:
-            telegram.InlineQueryResultArticle:
-        """
-        if not data:
-            return None
-        data = data.copy()
-        data.pop('type', None)
-
-        return InlineQueryResultArticle(**data)
-
-
-class InlineQueryResultPhoto(InlineQueryResult):
-    """This object represents a Telegram InlineQueryResultPhoto.
-
-    Attributes:
-        id (str):
-        photo_url (str):
-        mime_type (str):
-        photo_width (int):
-        photo_height (int):
-        thumb_url (str):
-        title (str):
-        description (str):
-        caption (str):
-        message_text (str):
-        parse_mode (str):
-        disable_web_page_preview (bool):
-
-    Args:
-        id (str): Unique identifier for this result, 1-64 Bytes
-        photo_url (str):
-        thumb_url (str):
-
-    Keyword Args:
-        mime_type (Optional[str]):
-        photo_width (Optional[int]):
-        photo_height (Optional[int]):
-        title (Optional[str]):
-        description (Optional[str]):
-        caption (Optional[str]):
-        message_text (Optional[str]):
-        parse_mode (Optional[str]):
-        disable_web_page_preview (Optional[bool]):
-    """
-
-    def __init__(self,
-                 id,
-                 photo_url,
-                 thumb_url,
-                 mime_type=None,
-                 photo_width=None,
-                 photo_height=None,
-                 title=None,
-                 description=None,
-                 caption=None,
-                 message_text=None,
-                 parse_mode=None,
-                 disable_web_page_preview=None):
-
-        validate_string(photo_url, 'photo_url')
-        validate_string(thumb_url, 'thumb_url')
-        validate_string(mime_type, 'mime_type')
-        validate_string(title, 'title')
-        validate_string(description, 'description')
-        validate_string(caption, 'caption')
-        validate_string(message_text, 'message_text')
-        validate_string(parse_mode, 'parse_mode')
-
-        # Required
-        super(InlineQueryResultPhoto, self).__init__('photo', id)
-        self.photo_url = photo_url
-        self.thumb_url = thumb_url
-
-        # Optional
-        self.mime_type = mime_type
-        if photo_width is not None:
-            self.photo_width = int(photo_width)
-        if photo_height is not None:
-            self.photo_height = int(photo_height)
-        self.title = title
-        self.description = description
-        self.caption = caption
-        self.message_text = message_text
-        self.parse_mode = parse_mode
-        self.disable_web_page_preview = bool(disable_web_page_preview)
-
-    @staticmethod
-    def de_json(data):
-        """
-        Args:
-            data (dict):
-
-        Returns:
-            telegram.InlineQueryResultPhoto:
-        """
-        if not data:
-            return None
-        data = data.copy()
-        data.pop('type', None)
-
-        return InlineQueryResultPhoto(**data)
-
-
-class InlineQueryResultGif(InlineQueryResult):
-    """This object represents a Telegram InlineQueryResultGif.
-
-    Attributes:
-        id (str):
-        gif_url (str):
-        gif_width (int):
-        gif_height (int):
-        thumb_url (str):
-        title (str):
-        caption (str):
-        message_text (str):
-        parse_mode (str):
-        disable_web_page_preview (bool):
-
-    Args:
-        id (str): Unique identifier for this result, 1-64 Bytes
-        gif_url (str):
-        thumb_url (str):
-
-    Keyword Args:
-        gif_width (Optional[int]):
-        gif_height (Optional[int]):
-        title (Optional[str]):
-        caption (Optional[str]):
-        message_text (Optional[str]):
-        parse_mode (Optional[str]):
-        disable_web_page_preview (Optional[bool]):
-    """
-
-    def __init__(self,
-                 id,
-                 gif_url,
-                 thumb_url,
-                 gif_width=None,
-                 gif_height=None,
-                 title=None,
-                 caption=None,
-                 message_text=None,
-                 parse_mode=None,
-                 disable_web_page_preview=None):
-
-        validate_string(gif_url, 'gif_url')
-        validate_string(thumb_url, 'thumb_url')
-        validate_string(title, 'title')
-        validate_string(caption, 'caption')
-        validate_string(message_text, 'message_text')
-        validate_string(parse_mode, 'parse_mode')
-
-        # Required
-        super(InlineQueryResultGif, self).__init__('gif', id)
-        self.gif_url = gif_url
-        self.thumb_url = thumb_url
-
-        # Optional
-        if gif_width is not None:
-            self.gif_width = int(gif_width)
-        if gif_height is not None:
-            self.gif_height = int(gif_height)
-        self.title = title
-        self.caption = caption
-        self.message_text = message_text
-        self.parse_mode = parse_mode
-        self.disable_web_page_preview = bool(disable_web_page_preview)
-
-    @staticmethod
-    def de_json(data):
-        """
-        Args:
-            data (dict):
-
-        Returns:
-            telegram.InlineQueryResultGif:
-        """
-        if not data:
-            return None
-        data = data.copy()
-        data.pop('type', None)
-
-        return InlineQueryResultGif(**data)
-
-
-class InlineQueryResultMpeg4Gif(InlineQueryResult):
-    """This object represents a Telegram InlineQueryResultMpeg4Gif.
-
-    Attributes:
-        id (str):
-        mpeg4_url (str):
-        mpeg4_width (int):
-        mpeg4_height (int):
-        thumb_url (str):
-        title (str):
-        caption (str):
-        message_text (str):
-        parse_mode (str):
-        disable_web_page_preview (bool):
-
-    Args:
-        id (str): Unique identifier for this result, 1-64 Bytes
-        mpeg4_url (str):
-        thumb_url (str):
-
-    Keyword Args:
-        mpeg4_width (Optional[int]):
-        mpeg4_height (Optional[int]):
-        title (Optional[str]):
-        caption (Optional[str]):
-        message_text (Optional[str]):
-        parse_mode (Optional[str]):
-        disable_web_page_preview (Optional[bool]):
-    """
-
-    def __init__(self,
-                 id,
-                 mpeg4_url,
-                 thumb_url,
-                 mpeg4_width=None,
-                 mpeg4_height=None,
-                 title=None,
-                 caption=None,
-                 message_text=None,
-                 parse_mode=None,
-                 disable_web_page_preview=None):
-
-        validate_string(mpeg4_url, 'mpeg4_url')
-        validate_string(thumb_url, 'thumb_url')
-        validate_string(title, 'title')
-        validate_string(caption, 'caption')
-        validate_string(message_text, 'message_text')
-        validate_string(parse_mode, 'parse_mode')
-
-        # Required
-        super(InlineQueryResultMpeg4Gif, self).__init__('mpeg4_gif', id)
-        self.mpeg4_url = mpeg4_url
-        self.thumb_url = thumb_url
-
-        # Optional
-        if mpeg4_width is not None:
-            self.mpeg4_width = int(mpeg4_width)
-        if mpeg4_height is not None:
-            self.mpeg4_height = int(mpeg4_height)
-        self.title = title
-        self.caption = caption
-        self.message_text = message_text
-        self.parse_mode = parse_mode
-        self.disable_web_page_preview = bool(disable_web_page_preview)
-
-    @staticmethod
-    def de_json(data):
-        """
-        Args:
-            data (dict):
-
-        Returns:
-            telegram.InlineQueryResultMpeg4Gif:
-        """
-        if not data:
-            return None
-        data = data.copy()
-        data.pop('type', None)
-
-        return InlineQueryResultMpeg4Gif(**data)
-
-
-class InlineQueryResultVideo(InlineQueryResult):
-    """This object represents a Telegram InlineQueryResultVideo.
-
-    Attributes:
-        id (str):
-        video_url (str):
-        mime_type (str):
-        video_width (int):
-        video_height (int):
-        video_duration (int):
-        thumb_url (str):
-        title (str):
-        description (str):
-        caption (str):
-        message_text (str):
-        parse_mode (str):
-        disable_web_page_preview (bool):
-
-    Args:
-        id (str): Unique identifier for this result, 1-64 Bytes
-        video_url (str):
-        mime_type (str):
-        thumb_url (str):
-        title (str):
-        message_text (str):
-
-    Keyword Args:
-        video_width (Optional[int]):
-        video_height (Optional[int]):
-        video_duration (Optional[int]):
-        description (Optional[str]):
-        caption (Optional[str]):
-        parse_mode (Optional[str]):
-        disable_web_page_preview (Optional[bool]):
-    """
-
-    def __init__(self,
-                 id,
-                 video_url,
-                 mime_type,
-                 thumb_url,
-                 title,
-                 message_text,
-                 video_width=None,
-                 video_height=None,
-                 video_duration=None,
-                 description=None,
-                 caption=None,
-                 parse_mode=None,
-                 disable_web_page_preview=None):
-
-        validate_string(video_url, 'video_url')
-        validate_string(mime_type, 'mime_type')
-        validate_string(thumb_url, 'thumb_url')
-        validate_string(title, 'title')
-        validate_string(message_text, 'message_text')
-        validate_string(description, 'description')
-        validate_string(caption, 'caption')
-        validate_string(parse_mode, 'parse_mode')
-
-        # Required
-        super(InlineQueryResultVideo, self).__init__('video', id)
-        self.video_url = video_url
-        self.mime_type = mime_type
-        self.thumb_url = thumb_url
-        self.title = title
-        self.message_text = message_text
-
-        # Optional
-        if video_width is not None:
-            self.video_width = int(video_width)
-        if video_height is not None:
-            self.video_height = int(video_height)
-        if video_duration is not None:
-            self.video_duration = int(video_duration)
-        self.description = description
-        self.caption = caption
-        self.parse_mode = parse_mode
-        self.disable_web_page_preview = bool(disable_web_page_preview)
-
-    @staticmethod
-    def de_json(data):
-        """
-        Args:
-            data (dict):
-
-        Returns:
-            telegram.InlineQueryResultVideo:
-        """
-        if not data:
-            return None
-        data = data.copy()
-        data.pop('type', None)
-
-        return InlineQueryResultVideo(**data)
+        return super(InlineQueryResult, InlineQueryResult).de_json(data)
@@ -0,0 +1,108 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InlineQueryResultArticle"""
+
+from telegram import InlineQueryResult, InlineKeyboardMarkup, \
+    InputMessageContent
+
+
+class InlineQueryResultArticle(InlineQueryResult):
+    """This object represents a Telegram InlineQueryResultArticle.
+
+    Attributes:
+        id (str):
+        title (str):
+        input_message_content (:class:`telegram.InputMessageContent`):
+        reply_markup (:class:`telegram.ReplyMarkup`):
+        url (str):
+        hide_url (bool):
+        description (str):
+        thumb_url (str):
+        thumb_width (int):
+        thumb_height (int):
+
+    Deprecated: 4.0
+        message_text (str): Use :class:`InputTextMessageContent` instead.
+
+        parse_mode (str): Use :class:`InputTextMessageContent` instead.
+
+        disable_web_page_preview (bool): Use :class:`InputTextMessageContent`
+        instead.
+
+    Args:
+        id (str): Unique identifier for this result, 1-64 Bytes
+        title (str):
+        reply_markup (:class:`telegram.ReplyMarkup`):
+
+    Keyword Args:
+        url (Optional[str]):
+        hide_url (Optional[bool]):
+        description (Optional[str]):
+        thumb_url (Optional[str]):
+        thumb_width (Optional[int]):
+        thumb_height (Optional[int]):
+    """
+
+    def __init__(self,
+                 id,
+                 title,
+                 input_message_content,
+                 reply_markup=None,
+                 url=None,
+                 hide_url=None,
+                 description=None,
+                 thumb_url=None,
+                 thumb_width=None,
+                 thumb_height=None,
+                 **kwargs):
+
+        # Required
+        super(InlineQueryResultArticle, self).__init__('article', id)
+        self.title = title
+        self.input_message_content = input_message_content
+
+        # Optional
+        if reply_markup:
+            self.reply_markup = reply_markup
+        if url:
+            self.url = url
+        if hide_url:
+            self.hide_url = hide_url
+        if description:
+            self.description = description
+        if thumb_url:
+            self.thumb_url = thumb_url
+        if thumb_width:
+            self.thumb_width = thumb_width
+        if thumb_height:
+            self.thumb_height = thumb_height
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineQueryResultArticle,
+                     InlineQueryResultArticle).de_json(data)
+
+        data['reply_markup'] = InlineKeyboardMarkup.de_json(
+            data.get('reply_markup'))
+        data['input_message_content'] = InputMessageContent.de_json(
+            data.get('input_message_content'))
+
+        return InlineQueryResultArticle(**data)
@@ -0,0 +1,97 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InlineQueryResultAudio"""
+
+from telegram import InlineQueryResult, InlineKeyboardMarkup, \
+    InputMessageContent
+
+
+class InlineQueryResultAudio(InlineQueryResult):
+    """Represents a link to an mp3 audio file. By default, this audio file will
+    be sent by the user. Alternatively, you can use input_message_content to
+    send a message with the specified content instead of the audio.
+
+    Attributes:
+        id (str):
+        audio_url (str):
+        title (str):
+        performer (Optional[str]):
+        audio_duration (Optional[str]):
+        reply_markup (Optional[:class:`telegram.InlineKeyboardMarkup`]):
+        input_message_content (Optional[
+            :class:`telegram.input_message_content`]):
+
+    Deprecated: 4.0
+        message_text (str): Use :class:`InputTextMessageContent` instead.
+
+        parse_mode (str): Use :class:`InputTextMessageContent` instead.
+
+        disable_web_page_preview (bool): Use :class:`InputTextMessageContent`
+        instead.
+
+    Args:
+        audio_url (str):
+        title (str):
+        **kwargs: Arbitrary keyword arguments.
+
+    Keyword Args:
+        performer (Optional[str]):
+        audio_duration (Optional[str]):
+        reply_markup (Optional[:class:`telegram.InlineKeyboardMarkup`]):
+        input_message_content (Optional[
+            :class:`telegram.input_message_content`]):
+    """
+    def __init__(self,
+                 id,
+                 audio_url,
+                 title,
+                 performer=None,
+                 audio_duration=None,
+                 reply_markup=None,
+                 input_message_content=None,
+                 **kwargs):
+
+        # Required
+        super(InlineQueryResultAudio, self).__init__('audio', id)
+        self.audio_url = audio_url
+        self.title = title
+
+        # Optionals
+        if performer:
+            self.performer = performer
+        if audio_duration:
+            self.audio_duration = audio_duration
+        if reply_markup:
+            self.reply_markup = reply_markup
+        if input_message_content:
+            self.input_message_content = input_message_content
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineQueryResultAudio,
+                     InlineQueryResultAudio).de_json(data)
+
+        data['reply_markup'] = InlineKeyboardMarkup.de_json(
+            data.get('reply_markup'))
+        data['input_message_content'] = InputMessageContent.de_json(
+            data.get('input_message_content'))
+
+        return InlineQueryResultAudio(**data)
@@ -0,0 +1,83 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InlineQueryResultCachedAudio"""
+
+from telegram import InlineQueryResult, InlineKeyboardMarkup, \
+    InputMessageContent
+
+
+class InlineQueryResultCachedAudio(InlineQueryResult):
+    """Represents a link to an mp3 audio file stored on the Telegram
+    servers. By default, this audio file will be sent by the user.
+    Alternatively, you can use input_message_content to send a message with
+    the specified content instead of the audio.
+
+    Attributes:
+        id (str):
+        audio_file_id (str):
+        reply_markup (Optional[:class:`telegram.InlineKeyboardMarkup`]):
+        input_message_content (Optional[
+            :class:`telegram.input_message_content`]):
+
+    Deprecated: 4.0
+        message_text (str): Use :class:`InputTextMessageContent` instead.
+
+        parse_mode (str): Use :class:`InputTextMessageContent` instead.
+
+        disable_web_page_preview (bool): Use :class:`InputTextMessageContent`
+        instead.
+
+    Args:
+        audio_file_id (str):
+        **kwargs: Arbitrary keyword arguments.
+
+    Keyword Args:
+        reply_markup (Optional[:class:`telegram.InlineKeyboardMarkup`]):
+        input_message_content (Optional[
+            :class:`telegram.input_message_content`]):
+    """
+    def __init__(self,
+                 id,
+                 audio_file_id,
+                 reply_markup=None,
+                 input_message_content=None,
+                 **kwargs):
+        # Required
+        super(InlineQueryResultCachedAudio, self).__init__('audio', id)
+        self.audio_file_id = audio_file_id
+
+        # Optionals
+        if reply_markup:
+            self.reply_markup = reply_markup
+        if input_message_content:
+            self.input_message_content = input_message_content
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineQueryResultCachedAudio,
+                     InlineQueryResultCachedAudio).de_json(data)
+
+        data['reply_markup'] = InlineKeyboardMarkup.de_json(
+            data.get('reply_markup'))
+        data['input_message_content'] = InputMessageContent.de_json(
+            data.get('input_message_content'))
+
+        return InlineQueryResultCachedAudio(**data)
@@ -0,0 +1,62 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InlineQueryResultCachedDocument"""
+
+from telegram import InlineQueryResult, InlineKeyboardMarkup, \
+    InputMessageContent
+
+
+class InlineQueryResultCachedDocument(InlineQueryResult):
+    def __init__(self,
+                 id,
+                 title,
+                 document_file_id,
+                 description=None,
+                 caption=None,
+                 reply_markup=None,
+                 input_message_content=None,
+                 **kwargs):
+        # Required
+        super(InlineQueryResultCachedDocument, self).__init__('document', id)
+        self.title = title
+        self.document_file_id = document_file_id
+
+        # Optionals
+        if description:
+            self.description = description
+        if caption:
+            self.caption = caption
+        if reply_markup:
+            self.reply_markup = reply_markup
+        if input_message_content:
+            self.input_message_content = input_message_content
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineQueryResultCachedDocument,
+                     InlineQueryResultCachedDocument).de_json(data)
+
+        data['reply_markup'] = InlineKeyboardMarkup.de_json(
+            data.get('reply_markup'))
+        data['input_message_content'] = InputMessageContent.de_json(
+            data.get('input_message_content'))
+
+        return InlineQueryResultCachedDocument(**data)
@@ -0,0 +1,60 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InlineQueryResultCachedGif"""
+
+from telegram import InlineQueryResult, InlineKeyboardMarkup, \
+    InputMessageContent
+
+
+class InlineQueryResultCachedGif(InlineQueryResult):
+    def __init__(self,
+                 id,
+                 gif_file_id,
+                 title=None,
+                 caption=None,
+                 reply_markup=None,
+                 input_message_content=None,
+                 **kwargs):
+        # Required
+        super(InlineQueryResultCachedGif, self).__init__('gif', id)
+        self.gif_file_id = gif_file_id
+
+        # Optionals
+        if title:
+            self.title = title
+        if caption:
+            self.caption = caption
+        if reply_markup:
+            self.reply_markup = reply_markup
+        if input_message_content:
+            self.input_message_content = input_message_content
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineQueryResultCachedGif,
+                     InlineQueryResultCachedGif).de_json(data)
+
+        data['reply_markup'] = InlineKeyboardMarkup.de_json(
+            data.get('reply_markup'))
+        data['input_message_content'] = InputMessageContent.de_json(
+            data.get('input_message_content'))
+
+        return InlineQueryResultCachedGif(**data)
@@ -0,0 +1,60 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InlineQueryResultMpeg4Gif"""
+
+from telegram import InlineQueryResult, InlineKeyboardMarkup, \
+    InputMessageContent
+
+
+class InlineQueryResultCachedMpeg4Gif(InlineQueryResult):
+    def __init__(self,
+                 id,
+                 mpeg4_file_id,
+                 title=None,
+                 caption=None,
+                 reply_markup=None,
+                 input_message_content=None,
+                 **kwargs):
+        # Required
+        super(InlineQueryResultCachedMpeg4Gif, self).__init__('mpeg4_gif', id)
+        self.mpeg4_file_id = mpeg4_file_id
+
+        # Optionals
+        if title:
+            self.title = title
+        if caption:
+            self.caption = caption
+        if reply_markup:
+            self.reply_markup = reply_markup
+        if input_message_content:
+            self.input_message_content = input_message_content
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineQueryResultCachedMpeg4Gif,
+                     InlineQueryResultCachedMpeg4Gif).de_json(data)
+
+        data['reply_markup'] = InlineKeyboardMarkup.de_json(
+            data.get('reply_markup'))
+        data['input_message_content'] = InputMessageContent.de_json(
+            data.get('input_message_content'))
+
+        return InlineQueryResultCachedMpeg4Gif(**data)
@@ -0,0 +1,63 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InlineQueryResultPhoto"""
+
+from telegram import InlineQueryResult, InlineKeyboardMarkup, \
+    InputMessageContent
+
+
+class InlineQueryResultCachedPhoto(InlineQueryResult):
+    def __init__(self,
+                 id,
+                 photo_file_id,
+                 title=None,
+                 description=None,
+                 caption=None,
+                 reply_markup=None,
+                 input_message_content=None,
+                 **kwargs):
+        # Required
+        super(InlineQueryResultCachedPhoto, self).__init__('photo', id)
+        self.photo_file_id = photo_file_id
+
+        # Optionals
+        if title:
+            self.title = title
+        if description:
+            self.description = description
+        if caption:
+            self.caption = caption
+        if reply_markup:
+            self.reply_markup = reply_markup
+        if input_message_content:
+            self.input_message_content = input_message_content
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineQueryResultCachedPhoto,
+                     InlineQueryResultCachedPhoto).de_json(data)
+
+        data['reply_markup'] = InlineKeyboardMarkup.de_json(
+            data.get('reply_markup'))
+        data['input_message_content'] = InputMessageContent.de_json(
+            data.get('input_message_content'))
+
+        return InlineQueryResultCachedPhoto(**data)
@@ -0,0 +1,54 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InlineQueryResultCachedSticker"""
+
+from telegram import InlineQueryResult, InlineKeyboardMarkup, \
+    InputMessageContent
+
+
+class InlineQueryResultCachedSticker(InlineQueryResult):
+    def __init__(self,
+                 id,
+                 sticker_file_id,
+                 reply_markup=None,
+                 input_message_content=None,
+                 **kwargs):
+        # Required
+        super(InlineQueryResultCachedSticker, self).__init__('sticker', id)
+        self.sticker_file_id = sticker_file_id
+
+        # Optionals
+        if reply_markup:
+            self.reply_markup = reply_markup
+        if input_message_content:
+            self.input_message_content = input_message_content
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineQueryResultCachedSticker,
+                     InlineQueryResultCachedSticker).de_json(data)
+
+        data['reply_markup'] = InlineKeyboardMarkup.de_json(
+            data.get('reply_markup'))
+        data['input_message_content'] = InputMessageContent.de_json(
+            data.get('input_message_content'))
+
+        return InlineQueryResultCachedSticker(**data)
@@ -0,0 +1,62 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InlineQueryResultCachedVideo"""
+
+from telegram import InlineQueryResult, InlineKeyboardMarkup, \
+    InputMessageContent
+
+
+class InlineQueryResultCachedVideo(InlineQueryResult):
+    def __init__(self,
+                 id,
+                 video_file_id,
+                 title,
+                 description=None,
+                 caption=None,
+                 reply_markup=None,
+                 input_message_content=None,
+                 **kwargs):
+        # Required
+        super(InlineQueryResultCachedVideo, self).__init__('video', id)
+        self.video_file_id = video_file_id
+        self.title = title
+
+        # Optionals
+        if description:
+            self.description = description
+        if caption:
+            self.caption = caption
+        if reply_markup:
+            self.reply_markup = reply_markup
+        if input_message_content:
+            self.input_message_content = input_message_content
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineQueryResultCachedVideo,
+                     InlineQueryResultCachedVideo).de_json(data)
+
+        data['reply_markup'] = InlineKeyboardMarkup.de_json(
+            data.get('reply_markup'))
+        data['input_message_content'] = InputMessageContent.de_json(
+            data.get('input_message_content'))
+
+        return InlineQueryResultCachedVideo(**data)
@@ -0,0 +1,59 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InlineQueryResultCachedVoice"""
+
+from telegram import InlineQueryResult, InlineKeyboardMarkup, \
+    InputMessageContent
+
+
+class InlineQueryResultCachedVoice(InlineQueryResult):
+    def __init__(self,
+                 id,
+                 voice_file_id,
+                 title,
+                 description=None,
+                 reply_markup=None,
+                 input_message_content=None,
+                 **kwargs):
+        # Required
+        super(InlineQueryResultCachedVoice, self).__init__('voice', id)
+        self.voice_file_id = voice_file_id
+        self.title = title
+
+        # Optionals
+        if description:
+            self.description = description
+        if reply_markup:
+            self.reply_markup = reply_markup
+        if input_message_content:
+            self.input_message_content = input_message_content
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineQueryResultCachedVoice,
+                     InlineQueryResultCachedVoice).de_json(data)
+
+        data['reply_markup'] = InlineKeyboardMarkup.de_json(
+            data.get('reply_markup'))
+        data['input_message_content'] = InputMessageContent.de_json(
+            data.get('input_message_content'))
+
+        return InlineQueryResultCachedVoice(**data)
@@ -0,0 +1,68 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InlineQueryResultContact"""
+
+from telegram import InlineQueryResult, InlineKeyboardMarkup, \
+    InputMessageContent
+
+
+class InlineQueryResultContact(InlineQueryResult):
+    def __init__(self,
+                 id,
+                 phone_number,
+                 first_name,
+                 last_name=None,
+                 reply_markup=None,
+                 input_message_content=None,
+                 thumb_url=None,
+                 thumb_width=None,
+                 thumb_height=None,
+                 **kwargs):
+        # Required
+        super(InlineQueryResultContact, self).__init__('contact', id)
+        self.phone_number = phone_number
+        self.first_name = first_name
+
+        # Optionals
+        if last_name:
+            self.last_name = last_name
+        if reply_markup:
+            self.reply_markup = reply_markup
+        if input_message_content:
+            self.input_message_content = input_message_content
+        if thumb_url:
+            self.thumb_url = thumb_url
+        if thumb_width:
+            self.thumb_width = thumb_width
+        if thumb_height:
+            self.thumb_height = thumb_height
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineQueryResultContact,
+                     InlineQueryResultContact).de_json(data)
+
+        data['reply_markup'] = InlineKeyboardMarkup.de_json(
+            data.get('reply_markup'))
+        data['input_message_content'] = InputMessageContent.de_json(
+            data.get('input_message_content'))
+
+        return InlineQueryResultContact(**data)
@@ -0,0 +1,73 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InlineQueryResultDocument"""
+
+from telegram import InlineQueryResult, InlineKeyboardMarkup, \
+    InputMessageContent
+
+
+class InlineQueryResultDocument(InlineQueryResult):
+    def __init__(self,
+                 id,
+                 document_url,
+                 title,
+                 mime_type,
+                 caption=None,
+                 description=None,
+                 reply_markup=None,
+                 input_message_content=None,
+                 thumb_url=None,
+                 thumb_width=None,
+                 thumb_height=None,
+                 **kwargs):
+        # Required
+        super(InlineQueryResultDocument, self).__init__('document', id)
+        self.document_url = document_url
+        self.title = title
+        self.mime_type = mime_type
+
+        # Optionals
+        if caption:
+            self.caption = caption
+        if description:
+            self.description = description
+        if reply_markup:
+            self.reply_markup = reply_markup
+        if input_message_content:
+            self.input_message_content = input_message_content
+        if thumb_url:
+            self.thumb_url = thumb_url
+        if thumb_width:
+            self.thumb_width = thumb_width
+        if thumb_height:
+            self.thumb_height = thumb_height
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineQueryResultDocument,
+                     InlineQueryResultDocument).de_json(data)
+
+        data['reply_markup'] = InlineKeyboardMarkup.de_json(
+            data.get('reply_markup'))
+        data['input_message_content'] = InputMessageContent.de_json(
+            data.get('input_message_content'))
+
+        return InlineQueryResultDocument(**data)
@@ -0,0 +1,69 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InlineQueryResultGif"""
+
+from telegram import InlineQueryResult, InlineKeyboardMarkup, \
+    InputMessageContent
+
+
+class InlineQueryResultGif(InlineQueryResult):
+    def __init__(self,
+                 id,
+                 gif_url,
+                 thumb_url,
+                 gif_width=None,
+                 gif_height=None,
+                 title=None,
+                 caption=None,
+                 reply_markup=None,
+                 input_message_content=None,
+                 **kwargs):
+
+        # Required
+        super(InlineQueryResultGif, self).__init__('gif', id)
+        self.gif_url = gif_url
+        self.thumb_url = thumb_url
+
+        # Optionals
+        if gif_width:
+            self.gif_width = gif_width
+        if gif_height:
+            self.gif_height = gif_height
+        if title:
+            self.title = title
+        if caption:
+            self.caption = caption
+        if reply_markup:
+            self.reply_markup = reply_markup
+        if input_message_content:
+            self.input_message_content = input_message_content
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineQueryResultGif,
+                     InlineQueryResultGif).de_json(data)
+
+        data['reply_markup'] = InlineKeyboardMarkup.de_json(
+            data.get('reply_markup'))
+        data['input_message_content'] = InputMessageContent.de_json(
+            data.get('input_message_content'))
+
+        return InlineQueryResultGif(**data)
@@ -0,0 +1,67 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InlineQueryResultLocation"""
+
+from telegram import InlineQueryResult, InlineKeyboardMarkup, \
+    InputMessageContent
+
+
+class InlineQueryResultLocation(InlineQueryResult):
+    def __init__(self,
+                 id,
+                 latitude,
+                 longitude,
+                 title,
+                 reply_markup=None,
+                 input_message_content=None,
+                 thumb_url=None,
+                 thumb_width=None,
+                 thumb_height=None,
+                 **kwargs):
+        # Required
+        super(InlineQueryResultLocation, self).__init__('location', id)
+        self.latitude = latitude
+        self.longitude = longitude
+        self.title = title
+
+        # Optionals
+        if reply_markup:
+            self.reply_markup = reply_markup
+        if input_message_content:
+            self.input_message_content = input_message_content
+        if thumb_url:
+            self.thumb_url = thumb_url
+        if thumb_width:
+            self.thumb_width = thumb_width
+        if thumb_height:
+            self.thumb_height = thumb_height
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineQueryResultLocation,
+                     InlineQueryResultLocation).de_json(data)
+
+        data['reply_markup'] = InlineKeyboardMarkup.de_json(
+            data.get('reply_markup'))
+        data['input_message_content'] = InputMessageContent.de_json(
+            data.get('input_message_content'))
+
+        return InlineQueryResultLocation(**data)
@@ -0,0 +1,69 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InlineQueryResultMpeg4Gif"""
+
+from telegram import InlineQueryResult, InlineKeyboardMarkup, \
+    InputMessageContent
+
+
+class InlineQueryResultMpeg4Gif(InlineQueryResult):
+    def __init__(self,
+                 id,
+                 mpeg4_url,
+                 thumb_url,
+                 mpeg4_width=None,
+                 mpeg4_height=None,
+                 title=None,
+                 caption=None,
+                 reply_markup=None,
+                 input_message_content=None,
+                 **kwargs):
+
+        # Required
+        super(InlineQueryResultMpeg4Gif, self).__init__('mpeg4_gif', id)
+        self.mpeg4_url = mpeg4_url
+        self.thumb_url = thumb_url
+
+        # Optional
+        if mpeg4_width:
+            self.mpeg4_width = mpeg4_width
+        if mpeg4_height:
+            self.mpeg4_height = mpeg4_height
+        if title:
+            self.title = title
+        if caption:
+            self.caption = caption
+        if reply_markup:
+            self.reply_markup = reply_markup
+        if input_message_content:
+            self.input_message_content = input_message_content
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineQueryResultMpeg4Gif,
+                     InlineQueryResultMpeg4Gif).de_json(data)
+
+        data['reply_markup'] = InlineKeyboardMarkup.de_json(
+            data.get('reply_markup'))
+        data['input_message_content'] = InputMessageContent.de_json(
+            data.get('input_message_content'))
+
+        return InlineQueryResultMpeg4Gif(**data)
@@ -0,0 +1,71 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InlineQueryResultPhoto"""
+
+from telegram import InlineQueryResult, InlineKeyboardMarkup, \
+    InputMessageContent
+
+
+class InlineQueryResultPhoto(InlineQueryResult):
+    def __init__(self,
+                 id,
+                 photo_url,
+                 thumb_url,
+                 photo_width=None,
+                 photo_height=None,
+                 title=None,
+                 description=None,
+                 caption=None,
+                 reply_markup=None,
+                 input_message_content=None,
+                 **kwargs):
+        # Required
+        super(InlineQueryResultPhoto, self).__init__('photo', id)
+        self.photo_url = photo_url
+        self.thumb_url = thumb_url
+
+        # Optionals
+        if photo_width:
+            self.photo_width = int(photo_width)
+        if photo_height:
+            self.photo_height = int(photo_height)
+        if title:
+            self.title = title
+        if description:
+            self.description = description
+        if caption:
+            self.caption = caption
+        if reply_markup:
+            self.reply_markup = reply_markup
+        if input_message_content:
+            self.input_message_content = input_message_content
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineQueryResultPhoto,
+                     InlineQueryResultPhoto).de_json(data)
+
+        data['reply_markup'] = InlineKeyboardMarkup.de_json(
+            data.get('reply_markup'))
+        data['input_message_content'] = InputMessageContent.de_json(
+            data.get('input_message_content'))
+
+        return InlineQueryResultPhoto(**data)
@@ -0,0 +1,73 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InlineQueryResultVenue"""
+
+from telegram import InlineQueryResult, InlineKeyboardMarkup, \
+    InputMessageContent
+
+
+class InlineQueryResultVenue(InlineQueryResult):
+    def __init__(self,
+                 id,
+                 latitude,
+                 longitude,
+                 title,
+                 address,
+                 foursquare_id=None,
+                 reply_markup=None,
+                 input_message_content=None,
+                 thumb_url=None,
+                 thumb_width=None,
+                 thumb_height=None,
+                 **kwargs):
+
+        # Required
+        super(InlineQueryResultVenue, self).__init__('venue', id)
+        self.latitude = latitude
+        self.longitude = longitude
+        self.title = title
+        self.address = address
+
+        # Optional
+        if foursquare_id:
+            self.foursquare_id = foursquare_id
+        if reply_markup:
+            self.reply_markup = reply_markup
+        if input_message_content:
+            self.input_message_content = input_message_content
+        if thumb_url:
+            self.thumb_url = thumb_url
+        if thumb_width:
+            self.thumb_width = thumb_width
+        if thumb_height:
+            self.thumb_height = thumb_height
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineQueryResultVenue,
+                     InlineQueryResultVenue).de_json(data)
+
+        data['reply_markup'] = InlineKeyboardMarkup.de_json(
+            data.get('reply_markup'))
+        data['input_message_content'] = InputMessageContent.de_json(
+            data.get('input_message_content'))
+
+        return InlineQueryResultVenue(**data)
@@ -0,0 +1,76 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InlineQueryResultVideo"""
+
+from telegram import InlineQueryResult, InlineKeyboardMarkup, \
+    InputMessageContent
+
+
+class InlineQueryResultVideo(InlineQueryResult):
+    def __init__(self,
+                 id,
+                 video_url,
+                 mime_type,
+                 thumb_url,
+                 title,
+                 caption=None,
+                 video_width=None,
+                 video_height=None,
+                 video_duration=None,
+                 description=None,
+                 reply_markup=None,
+                 input_message_content=None,
+                 **kwargs):
+
+        # Required
+        super(InlineQueryResultVideo, self).__init__('video', id)
+        self.video_url = video_url
+        self.mime_type = mime_type
+        self.thumb_url = thumb_url
+        self.title = title
+
+        # Optional
+        if caption:
+            self.caption = caption
+        if video_width:
+            self.video_width = video_width
+        if video_height:
+            self.video_height = video_height
+        if video_duration:
+            self.video_duration = video_duration
+        if description:
+            self.description = description
+        if reply_markup:
+            self.reply_markup = reply_markup
+        if input_message_content:
+            self.input_message_content = input_message_content
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineQueryResultVideo,
+                     InlineQueryResultVideo).de_json(data)
+
+        data['reply_markup'] = InlineKeyboardMarkup.de_json(
+            data.get('reply_markup'))
+        data['input_message_content'] = InputMessageContent.de_json(
+            data.get('input_message_content'))
+
+        return InlineQueryResultVideo(**data)
@@ -0,0 +1,60 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InlineQueryResultVoice"""
+
+from telegram import InlineQueryResult, InlineKeyboardMarkup, \
+    InputMessageContent
+
+
+class InlineQueryResultVoice(InlineQueryResult):
+    def __init__(self,
+                 id,
+                 voice_url,
+                 title,
+                 voice_duration=None,
+                 reply_markup=None,
+                 input_message_content=None,
+                 **kwargs):
+
+        # Required
+        super(InlineQueryResultVoice, self).__init__('voice', id)
+        self.voice_url = voice_url
+        self.title = title
+
+        # Optional
+        if voice_duration:
+            self.voice_duration = voice_duration
+        if reply_markup:
+            self.reply_markup = reply_markup
+        if input_message_content:
+            self.input_message_content = input_message_content
+
+    @staticmethod
+    def de_json(data):
+        data = super(InlineQueryResultVoice,
+                     InlineQueryResultVoice).de_json(data)
+
+        data['reply_markup'] = InlineKeyboardMarkup.de_json(
+            data.get('reply_markup'))
+        data['input_message_content'] = InputMessageContent.de_json(
+            data.get('input_message_content'))
+
+        return InlineQueryResultVoice(**data)
@@ -0,0 +1,41 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InputContactMessageContent"""
+
+from telegram import InputMessageContent
+
+
+class InputContactMessageContent(InputMessageContent):
+    """Base class for Telegram InputContactMessageContent Objects"""
+
+    def __init__(self,
+                 phone_number,
+                 first_name,
+                 last_name=None):
+        # Required
+        self.phone_number = phone_number
+        self.first_name = first_name
+        # Optionals
+        self.last_name = last_name
+
+    @staticmethod
+    def de_json(data):
+        return InputContactMessageContent(**data)
@@ -20,19 +20,18 @@

 """This module contains a object that represents a Telegram InputFile."""

-try:
-    from email.generator import _make_boundary as choose_boundary
-    from urllib.request import urlopen
-    from io import BufferedReader as file
-except ImportError:
-    from mimetools import choose_boundary
-    from urllib2 import urlopen
-
 import mimetypes
 import os
 import sys
 import imghdr

+try:
+    from email.generator import _make_boundary as choose_boundary
+    from urllib.request import urlopen
+except ImportError:
+    from mimetools import choose_boundary
+    from urllib2 import urlopen
+
 from telegram import TelegramError

 DEFAULT_MIME_TYPE = 'application/octet-stream'
@@ -76,16 +75,15 @@ class InputFile(object):
        else:
            from_url = False

-        if isinstance(self.input_file, file) or from_url:
+        if hasattr(self.input_file, 'read') or from_url:
            self.filename = None
            self.input_file_content = self.input_file.read()
            if 'filename' in data:
                self.filename = self.data.pop('filename')
-            elif isinstance(self.input_file, file) and \
-                    hasattr(self.input_file, 'name'):
+            elif hasattr(self.input_file, 'name'):
                self.filename = os.path.basename(self.input_file.name)
            elif from_url:
-                self.filename = os.path.basename(self.input_file.url)\
+                self.filename = os.path.basename(self.input_file.url) \
                    .split('?')[0].split('&')[0]

            try:
@@ -94,7 +92,7 @@ class InputFile(object):
                    self.filename = self.mimetype.replace('/', '.')
            except TelegramError:
                self.mimetype = mimetypes.guess_type(self.filename)[0] or \
-                    DEFAULT_MIME_TYPE
+                                DEFAULT_MIME_TYPE

    @property
    def headers(self):
@@ -198,7 +196,7 @@ class InputFile(object):
            if file_type:
                file_content = data[file_type[0]]

-                return isinstance(file_content, file) or \
-                    str(file_content).startswith('http')
+                return hasattr(file_content, 'read') or str(
+                    file_content).startswith('http')

        return False
@@ -0,0 +1,38 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InputLocationMessageContent"""
+
+from telegram import InputMessageContent
+
+
+class InputLocationMessageContent(InputMessageContent):
+    """Base class for Telegram InputLocationMessageContent Objects"""
+
+    def __init__(self,
+                 latitude,
+                 longitude):
+        # Required
+        self.latitude = latitude
+        self.longitude = longitude
+
+    @staticmethod
+    def de_json(data):
+        return InputLocationMessageContent(**data)
@@ -0,0 +1,60 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InputMessageContent"""
+
+from telegram import TelegramObject
+
+
+class InputMessageContent(TelegramObject):
+    """Base class for Telegram InputMessageContent Objects"""
+
+    @staticmethod
+    def de_json(data):
+        data = super(InputMessageContent, InputMessageContent).de_json(data)
+
+        if not data:
+            return None
+
+        try:
+            from telegram import InputTextMessageContent
+            return InputTextMessageContent.de_json(data)
+        except TypeError:
+            pass
+
+        try:
+            from telegram import InputLocationMessageContent
+            return InputLocationMessageContent.de_json(data)
+        except TypeError:
+            pass
+
+        try:
+            from telegram import InputVenueMessageContent
+            return InputVenueMessageContent.de_json(data)
+        except TypeError:
+            pass
+
+        try:
+            from telegram import InputContactMessageContent
+            return InputContactMessageContent.de_json(data)
+        except TypeError:
+            pass
+
+        return None
@@ -0,0 +1,41 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InputTextMessageContent"""
+
+from telegram import InputMessageContent
+
+
+class InputTextMessageContent(InputMessageContent):
+    """Base class for Telegram InputTextMessageContent Objects"""
+
+    def __init__(self,
+                 message_text,
+                 parse_mode=None,
+                 disable_web_page_preview=None):
+        # Required
+        self.message_text = message_text
+        # Optionals
+        self.parse_mode = parse_mode
+        self.disable_web_page_preview = disable_web_page_preview
+
+    @staticmethod
+    def de_json(data):
+        return InputTextMessageContent(**data)
@@ -0,0 +1,45 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 classes that represent Telegram
+InputVenueMessageContent"""
+
+from telegram import InputMessageContent
+
+
+class InputVenueMessageContent(InputMessageContent):
+    """Base class for Telegram InputVenueMessageContent Objects"""
+
+    def __init__(self,
+                 latitude,
+                 longitude,
+                 title,
+                 address,
+                 foursquare_id=None):
+        # Required
+        self.latitude = latitude
+        self.longitude = longitude
+        self.title = title
+        self.address = address
+        # Optionals
+        self.foursquare_id = foursquare_id
+
+    @staticmethod
+    def de_json(data):
+        return InputVenueMessageContent(**data)
@@ -0,0 +1,66 @@
+#!/usr/bin/env python
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# 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 a object that represents a Telegram KeyboardButton."""
+
+from telegram import TelegramObject
+
+
+class KeyboardButton(TelegramObject):
+    """
+    This object represents one button of the reply keyboard. For simple
+    text buttons String can be used instead of this object to specify text
+    of the button.
+
+    Args:
+        text (str):
+        request_location (Optional[bool]):
+        request_contact (Optional[bool]):
+    """
+
+    def __init__(self,
+                 text,
+                 request_contact=None,
+                 request_location=None):
+        # Required
+        self.text = text
+        # Optionals
+        if request_contact:
+            self.request_contact = request_contact
+        if request_location:
+            self.request_location = request_location
+
+    @staticmethod
+    def de_json(data):
+        if not data:
+            return None
+
+        return KeyboardButton(**data)
+
+    @staticmethod
+    def de_list(data):
+        if not data:
+            return []
+
+        keyboards = list()
+        for keyboard in data:
+            keyboards.append(KeyboardButton.
+                             de_json(keyboard))
+
+        return keyboards
@@ -24,7 +24,8 @@ from datetime import datetime
 from time import mktime

 from telegram import (Audio, Contact, Document, Chat, Location, PhotoSize,
-                      Sticker, TelegramObject, User, Video, Voice)
+                      Sticker, TelegramObject, User, Video, Voice, Venue,
+                      MessageEntity)


 class Message(TelegramObject):
@@ -50,8 +51,8 @@ class Message(TelegramObject):
        caption (str):
        contact (:class:`telegram.Contact`):
        location (:class:`telegram.Location`):
-        new_chat_participant (:class:`telegram.User`):
-        left_chat_participant (:class:`telegram.User`):
+        new_chat_member (:class:`telegram.User`):
+        left_chat_member (:class:`telegram.User`):
        new_chat_title (str):
        new_chat_photo (List[:class:`telegram.PhotoSize`]):
        delete_chat_photo (bool):
@@ -61,6 +62,13 @@ class Message(TelegramObject):
        migrate_from_chat_id (int):
        channel_chat_created (bool):

+    Deprecated: 4.0
+        new_chat_participant (:class:`telegram.User`): Use `new_chat_member`
+        instead.
+
+        left_chat_participant  (:class:`telegram.User`): Use `left_chat_member`
+        instead.
+
    Args:
        message_id (int):
        from_user (:class:`telegram.User`):
@@ -82,8 +90,8 @@ class Message(TelegramObject):
        caption (Optional[str]):
        contact (Optional[:class:`telegram.Contact`]):
        location (Optional[:class:`telegram.Location`]):
-        new_chat_participant (Optional[:class:`telegram.User`]):
-        left_chat_participant (Optional[:class:`telegram.User`]):
+        new_chat_member (Optional[:class:`telegram.User`]):
+        left_chat_member (Optional[:class:`telegram.User`]):
        new_chat_title (Optional[str]):
        new_chat_photo (Optional[List[:class:`telegram.PhotoSize`]):
        delete_chat_photo (Optional[bool]):
@@ -110,6 +118,7 @@ class Message(TelegramObject):
        self.forward_date = kwargs.get('forward_date')
        self.reply_to_message = kwargs.get('reply_to_message')
        self.text = kwargs.get('text', '')
+        self.entities = kwargs.get('entities', list())
        self.audio = kwargs.get('audio')
        self.document = kwargs.get('document')
        self.photo = kwargs.get('photo')
@@ -119,8 +128,9 @@ class Message(TelegramObject):
        self.caption = kwargs.get('caption', '')
        self.contact = kwargs.get('contact')
        self.location = kwargs.get('location')
-        self.new_chat_participant = kwargs.get('new_chat_participant')
-        self.left_chat_participant = kwargs.get('left_chat_participant')
+        self.venue = kwargs.get('venue')
+        self.new_chat_member = kwargs.get('new_chat_member')
+        self.left_chat_member = kwargs.get('left_chat_member')
        self.new_chat_title = kwargs.get('new_chat_title', '')
        self.new_chat_photo = kwargs.get('new_chat_photo')
        self.delete_chat_photo = bool(kwargs.get('delete_chat_photo', False))
@@ -131,6 +141,7 @@ class Message(TelegramObject):
        self.migrate_from_chat_id = int(kwargs.get('migrate_from_chat_id', 0))
        self.channel_chat_created = bool(kwargs.get('channel_chat_created',
                                                    False))
+        self.pinned_message = kwargs.get('pinned_message')

    @property
    def chat_id(self):
@@ -152,34 +163,24 @@ class Message(TelegramObject):
        data['from_user'] = User.de_json(data.get('from'))
        data['date'] = datetime.fromtimestamp(data['date'])
        data['chat'] = Chat.de_json(data.get('chat'))
-        data['forward_from'] = \
-            User.de_json(data.get('forward_from'))
-        data['forward_date'] = \
-            Message._fromtimestamp(data.get('forward_date'))
+        data['entities'] = MessageEntity.de_list(data.get('entities'))
+        data['forward_from'] = User.de_json(data.get('forward_from'))
+        data['forward_date'] = Message._fromtimestamp(data.get('forward_date'))
        data['reply_to_message'] = \
            Message.de_json(data.get('reply_to_message'))
-        data['audio'] = \
-            Audio.de_json(data.get('audio'))
-        data['document'] = \
-            Document.de_json(data.get('document'))
-        data['photo'] = \
-            PhotoSize.de_list(data.get('photo'))
-        data['sticker'] = \
-            Sticker.de_json(data.get('sticker'))
-        data['video'] = \
-            Video.de_json(data.get('video'))
-        data['voice'] = \
-            Voice.de_json(data.get('voice'))
-        data['contact'] = \
-            Contact.de_json(data.get('contact'))
-        data['location'] = \
-            Location.de_json(data.get('location'))
-        data['new_chat_participant'] = \
-            User.de_json(data.get('new_chat_participant'))
-        data['left_chat_participant'] = \
-            User.de_json(data.get('left_chat_participant'))
-        data['new_chat_photo'] = \
-            PhotoSize.de_list(data.get('new_chat_photo'))
+        data['audio'] = Audio.de_json(data.get('audio'))
+        data['document'] = Document.de_json(data.get('document'))
+        data['photo'] = PhotoSize.de_list(data.get('photo'))
+        data['sticker'] = Sticker.de_json(data.get('sticker'))
+        data['video'] = Video.de_json(data.get('video'))
+        data['voice'] = Voice.de_json(data.get('voice'))
+        data['contact'] = Contact.de_json(data.get('contact'))
+        data['location'] = Location.de_json(data.get('location'))
+        data['venue'] = Venue.de_json(data.get('venue'))
+        data['new_chat_member'] = User.de_json(data.get('new_chat_member'))
+        data['left_chat_member'] = User.de_json(data.get('left_chat_member'))
+        data['new_chat_photo'] = PhotoSize.de_list(data.get('new_chat_photo'))
+        data['pinned_message'] = Message.de_json(data.get('pinned_message'))

        return Message(**data)

@@ -204,6 +205,8 @@ class Message(TelegramObject):
            data['forward_date'] = self._totimestamp(self.forward_date)
        if self.photo:
            data['photo'] = [p.to_dict() for p in self.photo]
+        if self.entities:
+            data['entities'] = [e.to_dict() for e in self.entities]
        if self.new_chat_photo:
            data['new_chat_photo'] = [p.to_dict() for p in self.new_chat_photo]

--- a/Show More
+++ b/Show More