Release version 3.0.0

I think starting and setting the webhook should be two different tasks.
Because the internal webhook and the adress you see from outside can be
quite diffrent through apache etc. It provides more flexibility.

.travis.yml

@@ -7,9 +7,11 @@ python:
   - "pypy"
   - "pypy3"
 install:
-  - pip install coveralls
+  - pip install pylint flake8 coveralls
   - pip install -r requirements.txt
 script:
-  nosetests --with-coverage --cover-package telegram/
+  - nosetests --with-coverage --cover-package telegram/
+  - flake8 telegram
+  - 'if [[ $TRAVIS_PYTHON_VERSION != 2.6 ]]; then pylint -E telegram; fi'
 after_success:
   coveralls

AUTHORS.rst

@@ -9,6 +9,7 @@ Contributors
 The following wonderful people contributed directly or indirectly to this project:
 
 - `Avanatiker <https://github.com/Avanatiker>`_
+- `Balduro <https://github.com/Balduro>`_
 - `bimmlerd <https://github.com/bimmlerd>`_
 - `ErgoZ Riftbit Vaper <https://github.com/ergoz>`_
 - `franciscod <https://github.com/franciscod>`_
@@ -16,6 +17,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `jh0ker <https://github.com/jh0ker>`_
 - `JRoot3D <https://github.com/JRoot3D>`_
 - `macrojames <https://github.com/macrojames>`_
+- `naveenvhegde <https://github.com/naveenvhegde>`_
 - `njittam <https://github.com/njittam>`_
 - `Rahiel Kasim <https://github.com/rahiel>`_
 - `sooyhwang <https://github.com/sooyhwang>`_

CHANGES.rst

@@ -1,3 +1,15 @@
+**2015-12-08**
+
+*Released 3.0.0*
+
+- Introducing the ``Updater`` and ``Dispatcher`` classes
+
+**2015-11-11**
+
+*Released 2.9.2*
+
+- Error handling on request timeouts has been improved
+
 **2015-11-10**
 
 *Released 2.9.1*

MANIFEST.in

@@ -1 +1 @@
-include LICENSE LICENSE.lesser Makefile
+include LICENSE LICENSE.lesser Makefile requirements.txt

README.rst

@@ -54,11 +54,13 @@ Table of contents
 
   1. `API`_
 
-  2. `Logging`_
+  2. `The Updater class`_
+  
+  3. `Logging`_
 
-  3. `Examples`_
+  4. `Examples`_
 
-  4. `Documentation`_
+  5. `Documentation`_
 
 - `License`_
 
@@ -152,10 +154,72 @@ _`Getting started`
 
 View the last release API documentation at: https://core.telegram.org/bots/api
 
+------
+_`The Updater class`
+------
+
+The ``Updater`` class is the new way to create bots with ``python-telegram-bot``. It provides an easy-to-use interface to the ``telegram.Bot`` by caring about getting new updates from telegram and forwarding them to the ``Dispatcher`` class. We can register handler functions in the ``Dispatcher`` to make our bot react to Telegram commands, messages and even arbitrary updates.
+
+As with the old method, we'll need an Access Token. 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::
+
+   >>> from telegram import Updater
+   >>> updater = Updater(token='token')
+
+For quicker access to the ``Dispatcher`` used by our ``Updater``, we can introduce it locally::
+
+   >>> dispatcher = updater.dispatcher
+
+Now, we need to define a function that should process a specific type of update::
+
+   >>> 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::
+
+   >>> dispatcher.addTelegramCommandHandler('start', start)
+   
+The last step is to tell the ``Updater`` to start working::
+
+   >>> 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::
+
+   >>> def echo(bot, update):
+   ...   bot.sendMessage(chat_id=update.message.chat_id, text=update.message.text)
+   ...
+   >>> dispatcher.addTelegramMessageHandler(echo)
+
+Our bot should now reply to all 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::
+
+   >>> 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::
+
+   >>> 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)
+
+Now it's time to stop the bot::
+
+   >>> updater.stop()
+
+Check out more examples in the `examples folder <https://github.com/leandrotoledo/python-telegram-bot/tree/master/examples>`_!
+
 ------
 _`API`
 ------
 
+Note: Using the ``Bot`` class directly is the 'old' method, but some of this is still important information, even if you're using the ``Updater`` class!
+
 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>`_).
@@ -261,6 +325,8 @@ Here follows some examples to help you to get your own Bot up to speed:
 
 - `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).
 
+- `TwitterForwarderBot <https://github.com/franciscod/telegram-twitter-forwarder-bot>`_ forwards you tweets from people that you have subscribed to.
+
 ================
 _`Documentation`
 ================

docs/source/conf.py

@@ -58,9 +58,9 @@ author = u'Leandro Toledo'
 # built documents.
 #
 # The short X.Y version.
-version = '2.9'
+version = '3.0'
 # The full version, including alpha/beta/rc tags.
-release = '2.9.1'
+release = '3.0.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

examples/echobot.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python
+# -*- coding: utf-8 -*-
 #
-# Simple Bot to reply Telegram messages
+# Simple Bot to reply to Telegram messages
 # Copyright (C) 2015 Leandro Toledo de Souza <leandrotoeldodesouza@gmail.com>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -19,47 +20,60 @@
 
 import logging
 import telegram
+from time import sleep
 
-
-LAST_UPDATE_ID = None
+try:
+    from urllib.error import URLError
+except ImportError:
+    from urllib2 import URLError  # python 2
 
 
 def main():
-    global LAST_UPDATE_ID
+    # Telegram Bot Authorization Token
+    bot = telegram.Bot('TOKEN')
+
+    # get the first pending update_id, this is so we can skip over it in case
+    # we get an "Unauthorized" exception.
+    try:
+        update_id = bot.getUpdates()[0].update_id
+    except IndexError:
+        update_id = None
 
     logging.basicConfig(
         format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
 
-    # Telegram Bot Authorization Token
-    bot = telegram.Bot('TOKEN')
-
-    # This will be our global variable to keep the latest update_id when requesting
-    # for updates. It starts with the latest update_id if available.
-    try:
-        LAST_UPDATE_ID = bot.getUpdates()[-1].update_id
-    except IndexError:
-        LAST_UPDATE_ID = None
-
     while True:
-        echo(bot)
+        try:
+            update_id = echo(bot, update_id)
+        except telegram.TelegramError as e:
+            # These are network problems with Telegram.
+            if e.message in ("Bad Gateway", "Timed out"):
+                sleep(1)
+            elif e.message == "Unauthorized":
+                # The user has removed or blocked the bot.
+                update_id += 1
+            else:
+                raise e
+        except URLError as e:
+            # These are network problems on our end.
+            sleep(1)
 
 
-def echo(bot):
-    global LAST_UPDATE_ID
+def echo(bot, update_id):
 
-    # Request updates after the last updated_id
-    for update in bot.getUpdates(offset=LAST_UPDATE_ID, timeout=10):
-        # chat_id is required to reply any message
+    # Request updates after the last update_id
+    for update in bot.getUpdates(offset=update_id, timeout=10):
+        # chat_id is required to reply to any message
         chat_id = update.message.chat_id
-        reply_text = update.message.text
+        update_id = update.update_id + 1
+        message = update.message.text
 
-        if reply_text:
-            # Reply the message
+        if message:
+            # Reply to the message
             bot.sendMessage(chat_id=chat_id,
-                            text=reply_text)
+                            text=message)
 
-        # Updates global offset to get the new updates
-        LAST_UPDATE_ID = update.update_id + 1
+    return update_id
 
 
 if __name__ == '__main__':

examples/updater_bot.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python
+
+"""
+This Bot uses the Updater class to handle the bot.
+
+First, a few handler functions are defined. Then, those functions are passed to
+the Dispatcher and registered at their respective places.
+Then, the bot is started and the CLI-Loop is entered, where all text inputs are
+inserted into the update queue for the bot to handle.
+
+Usage:
+Basic Echobot example, repeats messages. Reply to last chat from the command
+line by typing "/reply <text>"
+Type 'stop' on the command line to stop the bot.
+"""
+
+from telegram import Updater
+from telegram.dispatcher import run_async
+from time import sleep
+import logging
+import sys
+
+root = logging.getLogger()
+root.setLevel(logging.INFO)
+
+ch = logging.StreamHandler(sys.stdout)
+ch.setLevel(logging.INFO)
+formatter = \
+    logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+ch.setFormatter(formatter)
+root.addHandler(ch)
+
+last_chat_id = 0
+
+logger = logging.getLogger(__name__)
+
+
+# Command Handlers
+def start(bot, update):
+    """ Answer in Telegram """
+    bot.sendMessage(update.message.chat_id, text='Hi!')
+
+
+def help(bot, update):
+    """ Answer in Telegram """
+    bot.sendMessage(update.message.chat_id, text='Help!')
+
+
+def any_message(bot, update):
+    """ Print to console """
+
+    # Save last chat_id to use in reply handler
+    global last_chat_id
+    last_chat_id = update.message.chat_id
+
+    logger.info("New message\nFrom: %s\nchat_id: %d\nText: %s" %
+                (update.message.from_user,
+                 update.message.chat_id,
+                 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):
+    """
+    Example for an asynchronous handler. It's not guaranteed that replies will
+    be in order when using @run_async.
+    """
+
+    sleep(2)  # IO-heavy operation here
+    bot.sendMessage(update.message.chat_id, text='Echo: %s' %
+                                                 update.message.text)
+
+
+def error(bot, update, error):
+    """ Print error to console """
+    logger.warn('Update %s caused error %s' % (update, error))
+
+
+def cli_reply(bot, update, args):
+    """
+    For any update of type telegram.Update or str, you can get the argument
+    list by appending args to the function parameters.
+    Here, we reply to the last active chat with the text after the command.
+    """
+    if last_chat_id is not 0:
+        bot.sendMessage(chat_id=last_chat_id, text=' '.join(args))
+
+
+def cli_noncommand(bot, update, update_queue):
+    """
+    You can also get the update queue as an argument in any handler by
+    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.
+    """
+    update_queue.put('/%s' % update)
+
+
+def unknown_cli_command(bot, update):
+    logger.warn("Command not found: %s" % update)
+
+
+def main():
+    # Create the EventHandler and pass it your bot's token.
+    token = 'token'
+    updater = Updater(token, workers=2)
+
+    # Get the dispatcher to register handlers
+    dp = updater.dispatcher
+
+    dp.addTelegramCommandHandler("start", start)
+    dp.addTelegramCommandHandler("help", help)
+    dp.addUnknownTelegramCommandHandler(unknown_command)
+    dp.addTelegramMessageHandler(message)
+    dp.addTelegramRegexHandler('.*', any_message)
+
+    dp.addStringCommandHandler('reply', cli_reply)
+    dp.addUnknownStringCommandHandler(unknown_cli_command)
+    dp.addStringRegexHandler('[^/].*', cli_noncommand)
+
+    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=20)
+
+    '''
+    # Alternatively, run with webhook:
+    updater.bot.setWebhook(webhook_url='https://example.com/%s' % token,
+                           certificate=open('cert.pem', 'wb'))
+
+    update_queue = updater.start_webhook('0.0.0.0',
+                                         443,
+                                         url_path=token,
+                                         cert='cert.pem',
+                                         key='key.key')
+
+    # 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)
+    '''
+
+    # Start CLI-Loop
+    while True:
+        try:
+            text = raw_input()
+        except NameError:
+            text = input()
+
+        # Gracefully stop the event handler
+        if text == 'stop':
+            updater.stop()
+            break
+
+        # else, put the text into the update queue
+        elif len(text) > 0:
+            update_queue.put(text)  # Put command into queue
+
+if __name__ == '__main__':
+    main()

examples/updater_simplebot.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python
+
+"""
+This Bot uses the Updater class to handle the bot.
+
+First, a few handler functions are defined. Then, those functions are passed to
+the Dispatcher and registered at their respective places.
+Then, the bot is started and the CLI-Loop is entered.
+
+Usage:
+Basic Echobot example, repeats messages.
+Type 'stop' on the command line to stop the bot.
+"""
+
+from telegram import Updater
+import logging
+import sys
+
+# Enable logging
+root = logging.getLogger()
+root.setLevel(logging.INFO)
+
+ch = logging.StreamHandler(sys.stdout)
+ch.setLevel(logging.DEBUG)
+formatter = \
+    logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+ch.setFormatter(formatter)
+root.addHandler(ch)
+
+logger = logging.getLogger(__name__)
+
+
+# Command Handlers
+def start(bot, update):
+    bot.sendMessage(update.message.chat_id, text='Hi!')
+
+
+def help(bot, update):
+    bot.sendMessage(update.message.chat_id, text='Help!')
+
+
+def echo(bot, update):
+    bot.sendMessage(update.message.chat_id, text=update.message.text)
+
+
+def error(bot, update, error):
+    logger.warn('Update "%s" caused error "%s"' % (update, error))
+
+
+def main():
+    # Create the EventHandler and pass it your bot's token.
+    updater = Updater("TOKEN")
+
+    # Get the dispatcher to register handlers
+    dp = updater.dispatcher
+
+    # on different commands - answer in Telegram
+    dp.addTelegramCommandHandler("start", start)
+    dp.addTelegramCommandHandler("help", help)
+
+    # on noncommand i.e message - echo the message on Telegram
+    dp.addTelegramMessageHandler(echo)
+
+    # on error - print error to stdout
+    dp.addErrorHandler(error)
+
+    # Start the Bot
+    updater.start_polling(timeout=5)
+
+    # Run the bot until the user presses Ctrl-C or the process receives SIGINT,
+    # SIGTERM or SIGABRT
+    updater.idle()
+
+if __name__ == '__main__':
+    main()

setup.py

@@ -26,7 +26,7 @@ def requirements():
 
 setup(
     name='python-telegram-bot',
-    version='2.9.1',
+    version='3.0.0',
     author='Leandro Toledo',
     author_email='leandrotoledodesouza@gmail.com',
     license='LGPLv3',

telegram/__init__.py

@@ -19,7 +19,7 @@
 """A library that provides a Python interface to the Telegram Bot API"""
 
 __author__ = 'leandrotoledodesouza@gmail.com'
-__version__ = '2.8.7'
+__version__ = '3.0.0'
 
 from .base import TelegramObject
 from .user import User
@@ -47,10 +47,12 @@ from .parsemode import ParseMode
 from .message import Message
 from .update import Update
 from .bot import Bot
+from .dispatcher import Dispatcher
+from .updater import Updater
 
-__all__ = ['Bot', 'Emoji', 'TelegramError', 'InputFile', 'ReplyMarkup',
-           'ForceReply', 'ReplyKeyboardHide', 'ReplyKeyboardMarkup',
-           'UserProfilePhotos', 'ChatAction', 'Location', 'Contact',
-           'Video', 'Sticker', 'Document', 'File', 'Audio', 'PhotoSize',
-           'GroupChat', 'Update', 'ParseMode', 'Message', 'User',
-           'TelegramObject', 'NullHandler', 'Voice']
+__all__ = ['Bot', 'Updater', 'Dispatcher', 'Emoji', 'TelegramError',
+           'InputFile', 'ReplyMarkup', 'ForceReply', 'ReplyKeyboardHide',
+           'ReplyKeyboardMarkup', 'UserProfilePhotos', 'ChatAction',
+           'Location', 'Contact', 'Video', 'Sticker', 'Document', 'File',
+           'Audio', 'PhotoSize', 'GroupChat', 'Update', 'ParseMode', 'Message',
+           'User', 'TelegramObject', 'NullHandler', 'Voice']

telegram/dispatcher.py

@@ -0,0 +1,593 @@
+#!/usr/bin/env python
+
+"""
+This module contains the Dispatcher class.
+"""
+import logging
+from functools import wraps
+from inspect import getargspec
+from threading import Thread, BoundedSemaphore, Lock
+from re import match
+
+from telegram import (TelegramError, Update, NullHandler)
+
+H = NullHandler()
+logging.getLogger(__name__).addHandler(H)
+
+semaphore = None
+running_async = 0
+async_lock = Lock()
+
+
+def run_async(func):
+    """
+    Function decorator that will run the function in a new thread.
+
+    Args:
+        func (function): The function to run in the thread.
+
+    Returns:
+        function:
+    """
+
+    @wraps(func)
+    def pooled(*args, **kwargs):
+        """
+        A wrapper to run a thread in a thread pool
+        """
+        global running_async, async_lock
+        result = func(*args, **kwargs)
+        semaphore.release()
+        with async_lock:
+            running_async -= 1
+        return result
+
+    @wraps(func)
+    def async_func(*args, **kwargs):
+        """
+        A wrapper to run a function in a thread
+        """
+        global running_async, async_lock
+        thread = Thread(target=pooled, args=args, kwargs=kwargs)
+        semaphore.acquire()
+        with async_lock:
+            running_async += 1
+        thread.start()
+        return thread
+
+    return async_func
+
+
+class Dispatcher:
+    """
+    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 other updates, args will be None
+
+    Attributes:
+
+    Args:
+        bot (telegram.Bot): The bot object that should be passed to the
+        handlers update_queue (queue.Queue): The synchronized queue that will
+        contain the updates.
+    """
+    def __init__(self, bot, update_queue, workers=4):
+        self.bot = bot
+        self.update_queue = update_queue
+        self.telegram_message_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.error_handlers = []
+        self.logger = logging.getLogger(__name__)
+        self.running = False
+
+        global semaphore
+        if not semaphore:
+            semaphore = BoundedSemaphore(value=workers)
+        else:
+            self.logger.info("Semaphore already initialized, skipping.")
+
+    class _Stop(object):
+        """
+        A class which objects can be passed into the update queue to stop the
+        thread
+        """
+        pass
+
+    def start(self):
+        """
+        Thread target of thread 'dispatcher'. Runs in background and processes
+        the update queue.
+        """
+
+        self.running = True
+        self.logger.info('Dispatcher thread started')
+
+        while True:
+            update = None
+
+            try:
+                # Pop update from update queue.
+                # Blocks if no updates are available.
+                update = self.update_queue.get()
+
+                if type(update) is self._Stop:
+                    break
+
+                self.processUpdate(update)
+                self.logger.debug('Processed Update: %s' % update)
+
+            # Dispatch any errors
+            except TelegramError as te:
+                self.logger.warn("Error was raised while processing Update.")
+                self.dispatchError(update, te)
+
+        self.logger.info('Dispatcher thread stopped')
+
+    def stop(self):
+        """
+        Stops the thread
+        """
+        if self.running:
+            self.running = False
+            self.update_queue.put(self._Stop())
+
+    def processUpdate(self, update):
+        """
+        Processes a single update.
+
+        Args:
+            update (any):
+        """
+
+        handled = False
+
+        # Custom type handlers
+        for t in self.type_handlers:
+            if isinstance(update, t):
+                self.dispatchType(update)
+                handled = True
+
+        # string update
+        if type(update) is str and update.startswith('/'):
+            self.dispatchStringCommand(update)
+            handled = True
+        elif type(update) is str:
+            self.dispatchStringRegex(update)
+            handled = True
+
+        # An error happened while polling
+        if isinstance(update, TelegramError):
+            self.dispatchError(None, update)
+            handled = True
+
+        # Telegram update (regex)
+        if isinstance(update, Update):
+            self.dispatchTelegramRegex(update)
+            handled = True
+
+        # Telegram update (command)
+        if isinstance(update, Update) \
+                and update.message.text.startswith('/'):
+            self.dispatchTelegramCommand(update)
+            handled = True
+
+        # Telegram update (message)
+        elif isinstance(update, Update):
+            self.dispatchTelegramMessage(update)
+            handled = True
+
+        # Update not recognized
+        if not handled:
+            self.dispatchError(update, TelegramError(
+                "Received update of unknown type %s" % type(update)))
+
+    # Add Handlers
+    def addTelegramMessageHandler(self, handler):
+        """
+        Registers a message handler in the Dispatcher.
+
+        Args:
+            handler (function): A function that takes (Bot, Update, *args) as
+                arguments.
+        """
+
+        self.telegram_message_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):
+        """
+        Registers an error handler in the Dispatcher.
+
+        Args:
+            handler (function): A function that takes (Bot, TelegramError) as
+                arguments.
+        """
+
+        self.error_handlers.append(handler)
+
+    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 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):
+        """
+        De-registers an error handler.
+
+        Args:
+            handler (any):
+        """
+
+        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):
+        """
+        Dispatches an update that contains a command.
+
+        Args:
+            command (str): The command keyword
+            update (telegram.Update): The Telegram update that contains the
+                command
+        """
+
+        command = update.message.text.split(' ')[0][1:].split('@')[0]
+
+        if command in self.telegram_command_handlers:
+            self.dispatchTo(self.telegram_command_handlers[command], update)
+        else:
+            self.dispatchTo(self.unknown_telegram_command_handlers, update)
+
+    def dispatchTelegramRegex(self, update):
+        """
+        Dispatches an update to all regex handlers that match the message
+        string.
+
+        Args:
+            command (str): The command keyword
+            update (telegram.Update): The Telegram update that contains the
+                command
+        """
+
+        matching_handlers = []
+
+        for matcher in self.telegram_regex_handlers:
+            if match(matcher, update.message.text):
+                for handler in self.telegram_regex_handlers[matcher]:
+                    matching_handlers.append(handler)
+
+        self.dispatchTo(matching_handlers, update)
+
+    def dispatchStringCommand(self, update):
+        """
+        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)
+        else:
+            self.dispatchTo(self.unknown_string_command_handlers, update)
+
+    def dispatchStringRegex(self, update):
+        """
+        Dispatches an update to all string regex handlers that match the
+        string.
+
+        Args:
+            command (str): The command keyword
+            update (telegram.Update): The Telegram update that contains the
+                command
+        """
+
+        matching_handlers = []
+
+        for matcher in self.string_regex_handlers:
+            if match(matcher, update):
+                for handler in self.string_regex_handlers[matcher]:
+                    matching_handlers.append(handler)
+
+        self.dispatchTo(matching_handlers, update)
+
+    def dispatchType(self, update):
+        """
+        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)
+        else:
+            self.dispatchError(update, TelegramError(
+                "Received update of unknown type %s" % type(update)))
+
+    def dispatchTelegramMessage(self, update):
+        """
+        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)
+
+    def dispatchError(self, update, error):
+        """
+        Dispatches an error.
+
+        Args:
+            update (any): The pdate 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):
+        """
+        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)
+
+    def call_handler(self, handler, update):
+        """
+        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
+        """
+        kwargs = {}
+        fargs = getargspec(handler).args
+
+        if 'update_queue' in fargs:
+            kwargs['update_queue'] = self.update_queue
+
+        if 'args' in fargs:
+            if isinstance(update, Update):
+                args = update.message.text.split(' ')[1:]
+            elif isinstance(update, str):
+                args = update.split(' ')[1:]
+            else:
+                args = None
+
+            kwargs['args'] = args
+
+        handler(self.bot, update, **kwargs)

telegram/updater.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python
+
+"""
+This module contains the class Updater, which tries to make creating Telegram
+Bots intuitive!
+"""
+import logging
+import os
+import ssl
+from threading import Thread
+from time import sleep
+import subprocess
+from signal import signal, SIGINT, SIGTERM, SIGABRT
+from telegram import (Bot, TelegramError, dispatcher, Dispatcher,
+                      NullHandler)
+from telegram.utils.webhookhandler import (WebhookServer, WebhookHandler)
+
+# Adjust for differences in Python versions
+try:
+    from Queue import Queue
+except ImportError:
+    from queue import Queue
+
+try:
+    from urllib2 import URLError
+except ImportError:
+    from urllib.error import URLError
+
+H = NullHandler()
+logging.getLogger(__name__).addHandler(H)
+
+
+class Updater:
+    """
+    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
+    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
+    handlers for different kinds of data: Updates from Telegram, basic text
+    commands and even arbitrary types.
+    The updater can be started as a polling service or, for production, use a
+    webhook to receive updates. This is achieved using the WebhookServer and
+    WebhookHandler classes.
+
+
+    Attributes:
+
+    Args:
+        token (str): The bots token given by the @BotFather
+        base_url (Optional[str]):
+        workers (Optional[int]): Amount of threads in the thread pool for
+            functions decorated with @run_async
+    """
+
+    def __init__(self, token, base_url=None, workers=4):
+
+        self.bot = Bot(token, base_url)
+        self.update_queue = Queue()
+        self.dispatcher = Dispatcher(self.bot, self.update_queue,
+                                     workers=workers)
+        self.last_update_id = 0
+        self.logger = logging.getLogger(__name__)
+        self.running = False
+        self.is_idle = False
+        self.httpd = None
+
+    def start_polling(self, poll_interval=1.0, timeout=10, network_delay=2):
+        """
+        Starts polling updates from Telegram.
+
+        Args:
+            poll_interval (Optional[float]): Time to wait between polling
+                updates from Telegram in seconds. Default is 1.0
+            timeout (Optional[float]): Passed to Bot.getUpdates
+            network_delay (Optional[float]): Passed to Bot.getUpdates
+
+        Returns:
+            Queue: The update queue that can be filled from the main thread
+        """
+
+        # Create Thread objects
+        dispatcher_thread = Thread(target=self.dispatcher.start,
+                                   name="dispatcher")
+        event_handler_thread = Thread(target=self._start_polling,
+                                      name="updater",
+                                      args=(poll_interval, timeout,
+                                            network_delay))
+
+        self.running = True
+
+        # Start threads
+        dispatcher_thread.start()
+        event_handler_thread.start()
+
+        # Return the update queue so the main thread can insert updates
+        return self.update_queue
+
+    def start_webhook(self,
+                      listen='127.0.0.1',
+                      port=80,
+                      url_path='',
+                      cert=None,
+                      key=None):
+        """
+        Starts a small http server to listen for updates via webhook. If cert
+        and key are not provided, the webhook will be started directly on
+        http://listen:port/url_path, so SSL can be handled by another
+        application. Else, the webhook will be started on
+        https://listen:port/url_path
+
+        Args:
+            listen (Optional[str]): IP-Address to listen on
+            port (Optional[int]): Port the bot should be listening on
+            url_path (Optional[str]): Path inside url
+            cert (Optional[str]): Path to the SSL certificate file
+            key (Optional[str]): Path to the SSL key file
+
+        Returns:
+            Queue: The update queue that can be filled from the main thread
+        """
+
+        # Create Thread objects
+        dispatcher_thread = Thread(target=self.dispatcher.start,
+                                   name="dispatcher")
+        event_handler_thread = Thread(target=self._start_webhook,
+                                      name="updater",
+                                      args=(listen, port, url_path, cert, key))
+
+        self.running = True
+
+        # Start threads
+        dispatcher_thread.start()
+        event_handler_thread.start()
+
+        # Return the update queue so the main thread can insert updates
+        return self.update_queue
+
+    def _start_polling(self, poll_interval, timeout, network_delay):
+        """
+        Thread target of thread 'updater'. Runs in background, pulls
+        updates from Telegram and inserts them in the update queue of the
+        Dispatcher.
+        """
+
+        current_interval = poll_interval
+        self.logger.info('Updater thread started')
+
+        # Remove webhook
+        self.bot.setWebhook(webhook_url=None)
+
+        while self.running:
+            try:
+                updates = self.bot.getUpdates(self.last_update_id,
+                                              timeout=timeout,
+                                              network_delay=network_delay)
+                if not self.running:
+                    if len(updates) > 0:
+                        self.logger.info('Updates ignored and will be pulled '
+                                         'again on restart.')
+                    break
+
+                for update in updates:
+                    self.update_queue.put(update)
+                    self.last_update_id = update.update_id + 1
+                    current_interval = poll_interval
+
+                sleep(current_interval)
+            except TelegramError as te:
+                # Put the error into the update queue and let the Dispatcher
+                # broadcast it
+                self.update_queue.put(te)
+                sleep(current_interval)
+
+            except URLError as e:
+                self.logger.error("Error while getting Updates: %s" % e)
+                # increase waiting times on subsequent errors up to 30secs
+                if current_interval < 30:
+                    current_interval += current_interval / 2
+                if current_interval > 30:
+                    current_interval = 30
+
+        self.logger.info('Updater thread stopped')
+
+    def _start_webhook(self, listen, port, url_path, cert, key):
+        self.logger.info('Updater thread started')
+        use_ssl = cert is not None and key is not None
+        url_path = "/%s" % url_path
+
+        # Create and start server
+        self.httpd = WebhookServer((listen, port), WebhookHandler,
+                                   self.update_queue, url_path)
+
+        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
+
+            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:
+                    raise TelegramError(str(error))
+            else:
+                raise TelegramError('SSL Certificate invalid')
+
+        self.httpd.serve_forever(poll_interval=1)
+        self.logger.info('Updater thread stopped')
+
+    def stop(self):
+        """
+        Stops the polling/webhook thread and the dispatcher
+        """
+        self.logger.info('Stopping Updater and Dispatcher...')
+        self.logger.debug('This might take a long time if you set a high value'
+                          ' as polling timeout.')
+        self.running = False
+
+        if self.httpd:
+            self.logger.info(
+                'Waiting for current webhook connection to be closed... '
+                'Send a Telegram message to the bot to exit immediately.')
+            self.httpd.shutdown()
+            self.httpd = None
+
+        self.logger.debug("Requesting Dispatcher to stop...")
+        self.dispatcher.stop()
+        while dispatcher.running_async > 0:
+            sleep(1)
+
+        self.logger.debug("Dispatcher stopped.")
+
+    def signal_handler(self, signum, frame):
+        self.is_idle = False
+        self.stop()
+
+    def idle(self, stop_signals=(SIGINT, SIGTERM, SIGABRT)):
+        """
+        Waits for the user to press Ctrl-C and stops the updater
+
+        Args:
+            stop_signals: Iterable containing signals from the signal module
+                that should be subscribed to. Updater.stop() will be called on
+                receiving one of those signals.
+        """
+        for sig in stop_signals:
+            signal(sig, self.signal_handler)
+
+        self.is_idle = True
+
+        while self.is_idle:
+            sleep(1)

telegram/utils/request.py

@@ -20,6 +20,7 @@
 """This module contains methods to make POST and GET requests"""
 
 import json
+import socket
 from ssl import SSLError
 
 try:
@@ -109,13 +110,17 @@ def post(url,
         if error.getcode() == 502:
             raise TelegramError('Bad Gateway')
 
-        message = _parse(error.read())
+        try:
+            message = _parse(error.read())
+        except ValueError:
+            message = 'Unknown HTTPError'
+
         raise TelegramError(message)
-    except SSLError as error:
-        if "operation timed out" in error.message:
+    except (SSLError, socket.timeout) as error:
+        if "operation timed out" in str(error):
             raise TelegramError("Timed out")
 
-        raise TelegramError(error.message)
+        raise TelegramError(str(error))
     return _parse(result)
 
 

telegram/utils/webhookhandler.py

@@ -0,0 +1,85 @@
+import logging
+
+from telegram import Update, NullHandler
+from future.utils import bytes_to_native_str as n
+from threading import Lock
+import json
+try:
+    import BaseHTTPServer
+except ImportError:
+    import http.server as BaseHTTPServer
+
+
+H = NullHandler()
+logging.getLogger(__name__).addHandler(H)
+
+
+class WebhookServer(BaseHTTPServer.HTTPServer, object):
+    def __init__(self, server_address, RequestHandlerClass, update_queue,
+                 webhook_path):
+        super(WebhookServer, self).__init__(server_address,
+                                            RequestHandlerClass)
+        self.logger = logging.getLogger(__name__)
+        self.update_queue = update_queue
+        self.webhook_path = webhook_path
+        self.is_running = False
+        self.server_lock = Lock()
+        self.shutdown_lock = Lock()
+
+    def serve_forever(self, poll_interval=0.5):
+        with self.server_lock:
+            self.is_running = True
+            self.logger.info("Webhook Server started.")
+            super(WebhookServer, self).serve_forever(poll_interval)
+            self.logger.info("Webhook Server stopped.")
+
+    def shutdown(self):
+        with self.shutdown_lock:
+            if not self.is_running:
+                self.logger.warn("Webhook Server already stopped.")
+                return
+            else:
+                super(WebhookServer, self).shutdown()
+                self.is_running = False
+
+
+# WebhookHandler, process webhook calls
+# Based on: https://github.com/eternnoir/pyTelegramBotAPI/blob/master/
+# examples/webhook_examples/webhook_cpython_echo_bot.py
+class WebhookHandler(BaseHTTPServer.BaseHTTPRequestHandler, object):
+    server_version = "WebhookHandler/1.0"
+
+    def __init__(self, request, client_address, server):
+        self.logger = logging.getLogger(__name__)
+        super(WebhookHandler, self).__init__(request, client_address, server)
+
+    def do_HEAD(self):
+        self.send_response(200)
+        self.end_headers()
+
+    def do_GET(self):
+        self.send_response(200)
+        self.end_headers()
+
+    def do_POST(self):
+        self.logger.debug("Webhook triggered")
+        if self.path == self.server.webhook_path and \
+           'content-type' in self.headers and \
+           'content-length' in self.headers and \
+           self.headers['content-type'] == 'application/json':
+            json_string = \
+                n(self.rfile.read(int(self.headers['content-length'])))
+
+            self.send_response(200)
+            self.end_headers()
+
+            self.logger.debug("Webhook received data: " + json_string)
+
+            update = Update.de_json(json.loads(json_string))
+            self.logger.info("Received Update with ID %d on Webhook" %
+                             update.update_id)
+            self.server.update_queue.put(update)
+
+        else:
+            self.send_error(403)
+            self.end_headers()

tests/test_bot.py

@@ -135,7 +135,7 @@ class BotTest(BaseTest, unittest.TestCase):
         upf = self._bot.getUserProfilePhotos(user_id=self._chat_id)
 
         self.assertTrue(self.is_json(upf.to_json()))
-        self.assertEqual(upf.photos[0][0].file_size, 6547)
+        self.assertEqual(upf.photos[0][0].file_size, 12421)
 
 if __name__ == '__main__':
     unittest.main()

tests/test_updater.py

@@ -0,0 +1,496 @@
+#!/usr/bin/env python
+# encoding: utf-8
+#
+# A library that provides a Python interface to the Telegram Bot API
+# Copyright (C) 2015 Leandro Toledo de Souza <leandrotoeldodesouza@gmail.com>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This 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 General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see [http://www.gnu.org/licenses/].
+
+"""
+This module contains a object that represents Tests for Updater, Dispatcher,
+WebhookServer and WebhookHandler
+"""
+import logging
+import unittest
+import sys
+import re
+import os
+import signal
+from random import randrange
+from time import sleep
+from datetime import datetime
+
+try:
+    from urllib2 import urlopen, Request
+except ImportError:
+    from urllib.request import Request, urlopen
+
+sys.path.append('.')
+
+from telegram import Update, Message, TelegramError, User, GroupChat, Updater
+from telegram.dispatcher import run_async
+from tests.base import BaseTest
+from threading import Lock, Thread
+
+# Enable logging
+root = logging.getLogger()
+root.setLevel(logging.INFO)
+
+ch = logging.StreamHandler(sys.stdout)
+ch.setLevel(logging.WARN)
+formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+ch.setFormatter(formatter)
+root.addHandler(ch)
+
+
+class UpdaterTest(BaseTest, unittest.TestCase):
+    """
+    This object represents Tests for Updater, Dispatcher, WebhookServer and
+    WebhookHandler
+    """
+
+    def setUp(self):
+        self.updater = Updater('', workers=2)
+
+        self.received_message = None
+        self.message_count = 0
+        self.lock = Lock()
+
+    def tearDown(self):
+        self.updater.stop()
+
+    def reset(self):
+        self.message_count = 0
+        self.received_message = None
+
+    def telegramHandlerTest(self, bot, update):
+        self.received_message = update.message.text
+        self.message_count += 1
+
+    @run_async
+    def asyncHandlerTest(self, bot, update):
+        sleep(1)
+        with self.lock:
+            self.received_message = update.message.text
+            self.message_count += 1
+
+    def stringHandlerTest(self, bot, update):
+        self.received_message = update
+        self.message_count += 1
+
+    def additionalArgsTest(self, bot, update, update_queue, args):
+        self.received_message = update
+        self.message_count += 1
+        if args[0] == 'resend':
+            update_queue.put('/test5 noresend')
+        elif args[0] == 'noresend':
+            pass
+
+    def errorRaisingHandlerTest(self, bot, update):
+        raise TelegramError(update)
+
+    def errorHandlerTest(self, bot, update, error):
+        self.received_message = error.message
+        self.message_count += 1
+
+    def test_addRemoveTelegramMessageHandler(self):
+        print('Testing add/removeTelegramMessageHandler')
+        bot = MockBot('Test')
+        self.updater.bot = bot
+        d = self.updater.dispatcher
+        d.addTelegramMessageHandler(
+            self.telegramHandlerTest)
+        self.updater.start_polling(0.01)
+        sleep(.1)
+        self.assertEqual(self.received_message, 'Test')
+
+        # Remove handler
+        d.removeTelegramMessageHandler(self.telegramHandlerTest)
+        self.reset()
+
+        bot.send_messages = 1
+        sleep(.1)
+        self.assertTrue(None is self.received_message)
+
+    def test_addTelegramMessageHandlerMultipleMessages(self):
+        print('Testing addTelegramMessageHandler and send 100 messages...')
+        self.updater.bot = MockBot('Multiple', 100)
+        self.updater.dispatcher.addTelegramMessageHandler(
+            self.telegramHandlerTest)
+        self.updater.start_polling(0.0)
+        sleep(2)
+        self.assertEqual(self.received_message, 'Multiple')
+        self.assertEqual(self.message_count, 100)
+
+    def test_addRemoveTelegramRegexHandler(self):
+        print('Testing add/removeStringRegexHandler')
+        bot = MockBot('Test2')
+        self.updater.bot = bot
+        d = self.updater.dispatcher
+        regobj = re.compile('Te.*')
+        self.updater.dispatcher.addTelegramRegexHandler(regobj,
+                                                        self.telegramHandlerTest)
+        self.updater.start_polling(0.01)
+        sleep(.1)
+        self.assertEqual(self.received_message, 'Test2')
+
+        # Remove handler
+        d.removeTelegramRegexHandler(regobj, self.telegramHandlerTest)
+        self.reset()
+
+        bot.send_messages = 1
+        sleep(.1)
+        self.assertTrue(None is self.received_message)
+
+    def test_addRemoveTelegramCommandHandler(self):
+        print('Testing add/removeTelegramCommandHandler')
+        bot = MockBot('/test')
+        self.updater.bot = bot
+        d = self.updater.dispatcher
+        self.updater.dispatcher.addTelegramCommandHandler(
+            'test', self.telegramHandlerTest)
+        self.updater.start_polling(0.01)
+        sleep(.1)
+        self.assertEqual(self.received_message, '/test')
+
+        # Remove handler
+        d.removeTelegramCommandHandler('test', self.telegramHandlerTest)
+        self.reset()
+
+        bot.send_messages = 1
+        sleep(.1)
+        self.assertTrue(None is self.received_message)
+
+    def test_addRemoveUnknownTelegramCommandHandler(self):
+        print('Testing add/removeUnknownTelegramCommandHandler')
+        bot = MockBot('/test2')
+        self.updater.bot = bot
+        d = self.updater.dispatcher
+        self.updater.dispatcher.addUnknownTelegramCommandHandler(
+            self.telegramHandlerTest)
+        self.updater.start_polling(0.01)
+        sleep(.1)
+        self.assertEqual(self.received_message, '/test2')
+
+        # Remove handler
+        d.removeUnknownTelegramCommandHandler(self.telegramHandlerTest)
+        self.reset()
+
+        bot.send_messages = 1
+        sleep(.1)
+        self.assertTrue(None is self.received_message)
+
+    def test_addRemoveStringRegexHandler(self):
+        print('Testing add/removeStringRegexHandler')
+        bot = MockBot('', messages=0)
+        self.updater.bot = bot
+        d = self.updater.dispatcher
+        d.addStringRegexHandler('Te.*', self.stringHandlerTest)
+        queue = self.updater.start_polling(0.01)
+        queue.put('Test3')
+        sleep(.1)
+        self.assertEqual(self.received_message, 'Test3')
+
+        # Remove handler
+        d.removeStringRegexHandler('Te.*', self.stringHandlerTest)
+        self.reset()
+
+        queue.put('Test3')
+        sleep(.1)
+        self.assertTrue(None is self.received_message)
+
+    def test_addRemoveStringCommandHandler(self):
+        print('Testing add/removeStringCommandHandler')
+        bot = MockBot('', messages=0)
+        self.updater.bot = bot
+        d = self.updater.dispatcher
+        d.addStringCommandHandler(
+            'test3', self.stringHandlerTest)
+
+        queue = self.updater.start_polling(0.01)
+        queue.put('/test3')
+        sleep(.1)
+        self.assertEqual(self.received_message, '/test3')
+
+        # Remove handler
+        d.removeStringCommandHandler('test3', self.stringHandlerTest)
+        self.reset()
+
+        queue.put('/test3')
+        sleep(.1)
+        self.assertTrue(None is self.received_message)
+
+    def test_addRemoveUnknownStringCommandHandler(self):
+        print('Testing add/removeUnknownStringCommandHandler')
+        bot = MockBot('/test')
+        self.updater.bot = bot
+        d = self.updater.dispatcher
+        d.addUnknownStringCommandHandler(
+            self.stringHandlerTest)
+        queue = self.updater.start_polling(0.01)
+        queue.put('/test4')
+        sleep(.1)
+        self.assertEqual(self.received_message, '/test4')
+
+        # Remove handler
+        d.removeUnknownStringCommandHandler(self.stringHandlerTest)
+        self.reset()
+
+        bot.send_messages = 1
+        sleep(.1)
+        self.assertTrue(None is self.received_message)
+
+    def test_addRemoveErrorHandler(self):
+        print('Testing add/removeErrorHandler')
+        bot = MockBot('', messages=0)
+        self.updater.bot = bot
+        d = self.updater.dispatcher
+        d.addErrorHandler(self.errorHandlerTest)
+        queue = self.updater.start_polling(0.01)
+        error = TelegramError("Unauthorized.")
+        queue.put(error)
+        sleep(.1)
+        self.assertEqual(self.received_message, "Unauthorized.")
+
+        # Remove handler
+        d.removeErrorHandler(self.errorHandlerTest)
+        self.reset()
+
+        queue.put(error)
+        sleep(.1)
+        self.assertTrue(None is self.received_message)
+
+    def test_errorInHandler(self):
+        print('Testing error in Handler')
+        bot = MockBot('', messages=0)
+        self.updater.bot = bot
+        d = self.updater.dispatcher
+        d.addStringRegexHandler('.*',
+                                                self.errorRaisingHandlerTest)
+        self.updater.dispatcher.addErrorHandler(self.errorHandlerTest)
+        queue = self.updater.start_polling(0.01)
+
+        queue.put('Test Error 1')
+        sleep(.1)
+        self.assertEqual(self.received_message, 'Test Error 1')
+
+    def test_errorOnGetUpdates(self):
+        print('Testing error on getUpdates')
+        bot = MockBot('', raise_error=True)
+        self.updater.bot = bot
+        d = self.updater.dispatcher
+        d.addErrorHandler(self.errorHandlerTest)
+        self.updater.start_polling(0.01)
+        sleep(.1)
+        self.assertEqual(self.received_message, "Test Error 2")
+
+    def test_addRemoveTypeHandler(self):
+        print('Testing add/removeTypeHandler')
+        bot = MockBot('', messages=0)
+        self.updater.bot = bot
+        d = self.updater.dispatcher
+        d.addTypeHandler(dict, self.stringHandlerTest)
+        queue = self.updater.start_polling(0.01)
+        payload = {"Test": 42}
+        queue.put(payload)
+        sleep(.1)
+        self.assertEqual(self.received_message, payload)
+
+        # Remove handler
+        d.removeTypeHandler(dict, self.stringHandlerTest)
+        self.reset()
+
+        queue.put(payload)
+        sleep(.1)
+        self.assertTrue(None is self.received_message)
+
+    def test_runAsync(self):
+        print('Testing @run_async')
+        bot = MockBot('Test5', messages=2)
+        self.updater.bot = bot
+        d = self.updater.dispatcher
+        d.addTelegramMessageHandler(
+            self.asyncHandlerTest)
+        self.updater.start_polling(0.01)
+        sleep(1.2)
+        self.assertEqual(self.received_message, 'Test5')
+        self.assertEqual(self.message_count, 2)
+
+    def test_additionalArgs(self):
+        print('Testing additional arguments for handlers')
+        self.updater.bot = MockBot('', messages=0)
+        self.updater.dispatcher.addStringCommandHandler(
+            'test5', self.additionalArgsTest)
+
+        queue = self.updater.start_polling(0.01)
+        queue.put('/test5 resend')
+        sleep(.1)
+        self.assertEqual(self.received_message, '/test5 noresend')
+        self.assertEqual(self.message_count, 2)
+
+    def test_webhook(self):
+        print('Testing Webhook')
+        bot = MockBot('', messages=0)
+        self.updater.bot = bot
+        d = self.updater.dispatcher
+        d.addTelegramMessageHandler(
+            self.telegramHandlerTest)
+
+        # Select random port for travis
+        port = randrange(1024, 49152)
+        self.updater.start_webhook('127.0.0.1', port,
+                                   url_path='TOKEN',
+                                   cert='./tests/test_updater.py',
+                                   key='./tests/test_updater.py')
+        sleep(0.5)
+        # SSL-Wrapping will fail, so we start the server without SSL
+        Thread(target=self.updater.httpd.serve_forever).start()
+
+        # Now, we send an update to the server via urlopen
+        message = Message(1, User(1, "Tester"), datetime.now(),
+                          GroupChat(1, "Test Group"))
+
+        message.text = "Webhook Test"
+        update = Update(1)
+        update.message = message
+
+        try:
+            payload = bytes(update.to_json(), encoding='utf-8')
+        except TypeError:
+            payload = bytes(update.to_json())
+
+        header = {
+            'content-type': 'application/json',
+            'content-length': str(len(payload))
+        }
+
+        r = Request('http://127.0.0.1:%d/TOKEN' % port,
+                    data=payload,
+                    headers=header)
+
+        urlopen(r)
+
+        sleep(1)
+        self.assertEqual(self.received_message, 'Webhook Test')
+
+        print("Test other webhook server functionalities...")
+        request = Request('http://localhost:%d/webookhandler.py' % port)
+        response = urlopen(request)
+        self.assertEqual(b'', response.read())
+        self.assertEqual(200, response.code)
+
+        request.get_method = lambda: 'HEAD'
+
+        response = urlopen(request)
+        self.assertEqual(b'', response.read())
+        self.assertEqual(200, response.code)
+
+        # Test multiple shutdown() calls
+        self.updater.httpd.shutdown()
+        self.updater.httpd.shutdown()
+        self.assertTrue(True)
+
+    def test_webhook_no_ssl(self):
+        print('Testing Webhook without SSL')
+        bot = MockBot('', messages=0)
+        self.updater.bot = bot
+        d = self.updater.dispatcher
+        d.addTelegramMessageHandler(
+            self.telegramHandlerTest)
+
+        # Select random port for travis
+        port = randrange(1024, 49152)
+        self.updater.start_webhook('127.0.0.1', port)
+        sleep(0.5)
+
+        # Now, we send an update to the server via urlopen
+        message = Message(1, User(1, "Tester 2"), datetime.now(),
+                          GroupChat(1, "Test Group 2"))
+
+        message.text = "Webhook Test 2"
+        update = Update(1)
+        update.message = message
+
+        try:
+            payload = bytes(update.to_json(), encoding='utf-8')
+        except TypeError:
+            payload = bytes(update.to_json())
+
+        header = {
+            'content-type': 'application/json',
+            'content-length': str(len(payload))
+        }
+
+        r = Request('http://127.0.0.1:%d/' % port,
+                    data=payload,
+                    headers=header)
+
+        urlopen(r)
+        sleep(1)
+        self.assertEqual(self.received_message, 'Webhook Test 2')
+
+    def signalsender(self):
+        sleep(0.5)
+        os.kill(os.getpid(), signal.SIGTERM)
+
+    def test_idle(self):
+        print('Testing idle')
+        self.updater.bot = MockBot('Test6', messages=0)
+        self.updater.start_polling(poll_interval=0.01)
+        Thread(target=self.signalsender).start()
+        self.updater.idle()
+        # If we get this far, idle() ran through
+        sleep(1)
+        self.updater.running = False
+
+
+class MockBot:
+
+    def __init__(self, text, messages=1, raise_error=False):
+        self.text = text
+        self.send_messages = messages
+        self.raise_error = raise_error
+        self.token = "TOKEN"
+        pass
+
+    @staticmethod
+    def mockUpdate(text):
+        message = Message(0, None, None, None)
+        message.text = text
+        update = Update(0)
+        update.message = message
+        return update
+
+    def setWebhook(self, webhook_url=None, certificate=None):
+        pass
+
+    def getUpdates(self,
+                   offset=None,
+                   limit=100,
+                   timeout=0,
+                   network_delay=2.):
+
+        if self.raise_error:
+            raise TelegramError('Test Error 2')
+        elif self.send_messages >= 2:
+            self.send_messages -= 2
+            return self.mockUpdate(self.text), self.mockUpdate(self.text)
+        elif self.send_messages == 1:
+            self.send_messages -= 1
+            return self.mockUpdate(self.text),
+        else:
+            return []
+
+if __name__ == '__main__':
+    unittest.main()