Bump version to v5.0.0

* initial commit for conversationhandler and example

* implement simple Promise for run_async/conversationhandler

* refactor Promise._done to done

* add handling for timed out Promises

* correctly handle promises with None results

* fix handling tuple states

* update comments on example

* Added a first test on the ConversationHandler.

* Fixed a small typo.

* Yapf'd.

* add sphinx doc for conversation handler

* fix title for callbackqueryhandler sphinx docs

.github/CONTRIBUTING.rst

@@ -1,34 +1,41 @@
 How To Contribute
-=================
+===================
 
 Every open source project lives from the generous help by contributors that sacrifice their time and ``python-telegram-bot`` is no different. To make participation as pleasant as possible, this project adheres to the `Code of Conduct`_ by the Python Software Foundation.
 
 Setting things up
------------------
+-------------------
 
 1. Fork the ``python-telegram-bot`` repository to your GitHub account.
 
 2. Clone your forked repository of ``python-telegram-bot`` to your computer:
 
-   ``$ git clone https://github.com/<your username>/python-telegram-bot``
+   .. code-block:: bash
 
-   ``$ cd python-telegram-bot``
+      $ git clone https://github.com/<your username>/python-telegram-bot
+      $ cd python-telegram-bot
 
 3. Add a track to the original repository:
 
-   ``$ git remote add upstream https://github.com/python-telegram-bot/python-telegram-bot``
+   .. code-block:: bash
+
+      $ git remote add upstream https://github.com/python-telegram-bot/python-telegram-bot
 
 4. Install dependencies:
 
-   ``$ pip install -r requirements.txt -r requirements-dev.txt``
+   .. code-block:: bash
+
+      $ sudo pip install -r requirements.txt -r requirements-dev.txt
 
 
 5. Install pre-commit hooks:
 
-   ``$ pre-commit install``
+   .. code-block:: bash
+
+      $ pre-commit install
 
 Finding something to do
------------------------
+###################
 
 If you already know what you'd like to work on, you can skip this section.
 
@@ -37,7 +44,7 @@ If you have an idea for something to do, first check if it's already been filed
 Another great way to start contributing is by writing tests. Tests are really important because they help prevent developers from accidentally breaking existing code, allowing them to build cool things faster. If you're interested in helping out, let the development team know by posting to the `developers' mailing list`_, and we'll help you get started.
 
 Instructions for making a code change
--------------------------------------
+####################
 
 The central development branch is ``master``, which should be clean and ready for release at any time. In general, all changes should be done as feature branches based off of ``master``.
 
@@ -47,13 +54,12 @@ Here's how to make a one-off code change.
 
 2. **Create a new branch with this name, starting from** ``master``. In other words, run:
 
-   ``$ git fetch upstream``
+   .. code-block:: bash
 
-   ``$ git checkout master``
-
-   ``$ git merge upstream/master``
-
-   ``$ git checkout -b your-branch-name``
+      $ git fetch upstream
+      $ git checkout master
+      $ git merge upstream/master
+      $ git checkout -b your-branch-name
 
 3. **Make a commit to your feature branch**. Each commit should be self-contained and have a descriptive commit message that helps other developers understand why the changes were made.
 
@@ -75,19 +81,27 @@ Here's how to make a one-off code change.
 
    - Before making a commit ensure that all automated tests still pass:
 
-      ``$ make test``
+     .. code-block::
+
+        $ make test
 
    - To actually make the commit (this will trigger tests for yapf, lint and pep8 automatically):
 
-      ``$ git add your-file-changed.py``
+     .. code-block:: bash
 
-        - yapf may change code formatting, make sure to re-add them to your commit.
+        $ git add your-file-changed.py
 
-      ``$ git commit -a -m "your-commit-message-here"``
+   - yapf may change code formatting, make sure to re-add them to your commit.
+
+     .. code-block:: bash
+
+      $ git commit -a -m "your-commit-message-here"
 
    - Finally, push it to your GitHub fork, run:
 
-      ``$ git push origin your-branch-name``
+     .. code-block:: bash
+
+      $ git push origin your-branch-name
 
 4. **When your feature is ready to merge, create a pull request.**
 
@@ -107,66 +121,67 @@ Here's how to make a one-off code change.
 
    - Resolve any merge conflicts that arise. To resolve conflicts between 'your-branch-name' (in your fork) and 'master' (in the ``python-telegram-bot`` repository), run:
 
-      ``$ git checkout your-branch-name``
+     .. code-block:: bash
 
-      ``$ git fetch upstream``
-
-      ``$ git merge upstream/master``
-
-      ``$ ...[fix the conflicts]...``
-
-      ``$ ...[make sure the tests pass before committing]...``
-
-      ``$ git commit -a``
-
-      ``$ git push origin your-branch-name``
+      	$ git checkout your-branch-name
+      	$ git fetch upstream
+	$ git merge upstream/master
+      	$ ...[fix the conflicts]...
+      	$ ...[make sure the tests pass before committing]...
+      	$ git commit -a
+      	$ git push origin your-branch-name
 
    - At the end, the reviewer will merge the pull request.
 
 6. **Tidy up!** Delete the feature branch from both your local clone and the GitHub repository:
 
-   ``$ git branch -D your-branch-name``
+   .. code-block:: bash
 
-   ``$ git push origin --delete your-branch-name``
+      $ git branch -D your-branch-name
+      $ git push origin --delete your-branch-name
 
 7. **Celebrate.** Congratulations, you have contributed to ``python-telegram-bot``!
 
 Style commandments
-==================
+---------------------
 
 Specific commandments
----------------------
+#####################
 
 - Avoid using "double quotes" where you can reasonably use 'single quotes'.
 
 AssertEqual argument order
---------------------------
+######################
 
-assertEqual method's arguments should be in ('actual', 'expected') order.
+- assertEqual method's arguments should be in ('actual', 'expected') order.
 
 Properly calling callables
---------------------------
+#######################
 
 Methods, functions and classes can specify optional parameters (with default
 values) using Python's keyword arg syntax. When providing a value to such a
-callable we prefer that the call also uses keyword arg syntax. For example::
+callable we prefer that the call also uses keyword arg syntax. For example:
 
-    # GOOD
-    f(0, optional=True)
+.. code-block:: python
 
-    # BAD
-    f(0, True)
+   # GOOD
+   f(0, optional=True)
+
+   # BAD
+   f(0, True)
 
 This gives us the flexibility to re-order arguments and more importantly
 to add new required arguments. It's also more explicit and easier to read.
 
 Properly defining optional arguments
-------------------------------------
+########################
 
-It's always good to not initialize optional arguments at class creation, 
-instead use ``**kwargs`` to get them. It's well known Telegram API can 
-change without notice, in that case if a new argument is added it won't 
-break the API classes. For example::
+It's always good to not initialize optional arguments at class creation,
+instead use ``**kwargs`` to get them. It's well known Telegram API can
+change without notice, in that case if a new argument is added it won't
+break the API classes. For example:
+
+.. code-block:: python
 
     # GOOD
     def __init__(self, id, name, **kwargs):
@@ -183,4 +198,4 @@ break the API classes. For example::
 .. _`PEP 8 Style Guide`: https://www.python.org/dev/peps/pep-0008/
 .. _`Google Python Style Guide`: https://google-styleguide.googlecode.com/svn/trunk/pyguide.html
 .. _`Google Python Style Docstrings`: http://sphinx-doc.org/latest/ext/example_google.html
-.. _AUTHORS.rst: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/AUTHORS.rst
+.. _AUTHORS.rst: ../AUTHORS.rst

.pre-commit-config.yaml

@@ -4,7 +4,7 @@
     -   id: yapf
         files: ^(telegram|tests)/.*\.py$
 -   repo: git://github.com/pre-commit/pre-commit-hooks
-    sha: 6dfcb89af3c9b4d172cc2e5a8a2fa0f54615a338
+    sha: 3fa02652357ff0dbb42b5bc78c673b7bc105fcf3
     hooks:
     -   id: flake8
         files: ^telegram/.*\.py$

AUTHORS.rst

@@ -25,6 +25,7 @@ The following wonderful people contributed directly or indirectly to this projec
 - `Rahiel Kasim <https://github.com/rahiel>`_
 - `Shelomentsev D <https://github.com/shelomentsevd>`_
 - `sooyhwang <https://github.com/sooyhwang>`_
+- `Valentijn <https://github.com/Faalentijn>`_
 - `wjt <https://github.com/wjt>`_
 
 Please add yourself here alphabetically when you submit your first pull request.

CHANGES.rst

@@ -1,3 +1,38 @@
+=======
+Changes
+=======
+
+**2016-07-15**
+
+*Released 5.0*
+
+- Rework ``JobQueue``
+- Introduce ``ConversationHandler``
+
+**2016-07-12**
+
+*Released 4.3.4*
+
+- Fix proxy support with ``urllib3`` when proxy requires auth
+
+**2016-07-08**
+
+*Released 4.3.3*
+
+- Fix proxy support with ``urllib3``
+
+**2016-07-04**
+
+*Released 4.3.2*
+
+- Fix: Use ``timeout`` parameter in all API methods
+
+**2016-06-29**
+
+*Released 4.3.1*
+
+- Update wrong requirement: ``urllib3>=1.10``
+
 **2016-06-28**
 
 *Released 4.3*

docs/Makefile

@@ -189,4 +189,4 @@ xml:
 pseudoxml:
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
-	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

docs/source/index.rst

@@ -7,6 +7,7 @@ Welcome to Python Telegram Bot's documentation!
 ===============================================
 
 Contents:
+   telegram
 
 .. toctree::
    :maxdepth: 2

docs/source/telegram.constants.rst

@@ -0,0 +1,7 @@
+telegram.constants module
+=========================
+
+.. automodule:: telegram.constants
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/telegram.ext.callbackqueryhandler.rst

@@ -1,7 +1,7 @@
-telegram.ext.handler module
-===========================
+telegram.ext.callbackqueryhandler module
+========================================
 
-.. automodule:: telegram.ext.handler
+.. automodule:: telegram.ext.callbackqueryhandler
     :members:
     :undoc-members:
     :show-inheritance:

docs/source/telegram.ext.conversationhandler.rst

@@ -0,0 +1,7 @@
+telegram.ext.conversationhandler module
+=======================================
+
+.. automodule:: telegram.ext.conversationhandler
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/telegram.ext.rst

@@ -11,6 +11,7 @@ Submodules
     telegram.ext.jobqueue
     telegram.ext.handler
     telegram.ext.choseninlineresulthandler
+    telegram.ext.conversationhandler
     telegram.ext.commandhandler
     telegram.ext.inlinequeryhandler
     telegram.ext.messagehandler

examples/conversationbot.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# Simple Bot to reply to Telegram messages
+# This program is dedicated to the public domain under the CC0 license.
+"""
+This Bot uses the Updater class to handle the bot.
+
+First, a few callback functions are defined. Then, those functions are passed to
+the Dispatcher and registered at their respective places.
+Then, the bot is started and runs until we press Ctrl-C on the command line.
+
+Usage:
+Example of a bot-user conversation using ConversationHandler.
+Send /start to initiate the conversation.
+Press Ctrl-C on the command line or send a signal to the process to stop the
+bot.
+"""
+
+from telegram import (ReplyKeyboardMarkup)
+from telegram.ext import (Updater, CommandHandler, MessageHandler, Filters, RegexHandler,
+                          ConversationHandler)
+
+import logging
+
+# Enable logging
+logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+                    level=logging.INFO)
+
+logger = logging.getLogger(__name__)
+
+GENDER, PHOTO, LOCATION, BIO = range(4)
+
+
+def start(bot, update):
+    reply_keyboard = [['Boy', 'Girl', 'Other']]
+
+    bot.sendMessage(update.message.chat_id,
+                    text='Hi! My name is Professor Bot. I will hold a conversation with you. '
+                         'Send /cancel to stop talking to me.\n\n'
+                         'Are you a boy or a girl?',
+                    reply_markup=ReplyKeyboardMarkup(reply_keyboard, one_time_keyboard=True))
+
+    return GENDER
+
+
+def gender(bot, update):
+    user = update.message.from_user
+    logger.info("Gender of %s: %s" % (user.first_name, update.message.text))
+    bot.sendMessage(update.message.chat_id,
+                    text='I see! Please send me a photo of yourself, '
+                         'so I know what you look like, or send /skip if you don\'t want to.')
+
+    return PHOTO
+
+
+def photo(bot, update):
+    user = update.message.from_user
+    photo_file = bot.getFile(update.message.photo[-1].file_id)
+    photo_file.download('user_photo.jpg')
+    logger.info("Photo of %s: %s" % (user.first_name, 'user_photo.jpg'))
+    bot.sendMessage(update.message.chat_id, text='Gorgeous! Now, send me your location please, '
+                                                 'or send /skip if you don\'t want to.')
+
+    return LOCATION
+
+
+def skip_photo(bot, update):
+    user = update.message.from_user
+    logger.info("User %s did not send a photo." % user.first_name)
+    bot.sendMessage(update.message.chat_id, text='I bet you look great! Now, send me your '
+                                                 'location please, or send /skip.')
+
+    return LOCATION
+
+
+def location(bot, update):
+    user = update.message.from_user
+    user_location = update.message.location
+    logger.info("Location of %s: %f / %f"
+                % (user.first_name, user_location.latitude, user_location.longitude))
+    bot.sendMessage(update.message.chat_id, text='Maybe I can visit you sometime! '
+                                                 'At last, tell me something about yourself.')
+
+    return BIO
+
+
+def skip_location(bot, update):
+    user = update.message.from_user
+    logger.info("User %s did not send a location." % user.first_name)
+    bot.sendMessage(update.message.chat_id, text='You seem a bit paranoid! '
+                                                 'At last, tell me something about yourself.')
+
+    return BIO
+
+
+def bio(bot, update):
+    user = update.message.from_user
+    logger.info("Bio of %s: %s" % (user.first_name, update.message.text))
+    bot.sendMessage(update.message.chat_id,
+                    text='Thank you! I hope we can talk again some day.')
+
+    return ConversationHandler.END
+
+
+def cancel(bot, update):
+    user = update.message.from_user
+    logger.info("User %s canceled the conversation." % user.first_name)
+    bot.sendMessage(update.message.chat_id,
+                    text='Bye! I hope we can talk again some day.')
+
+    return ConversationHandler.END
+
+
+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
+
+    # Add conversation handler with the states GENDER, PHOTO, LOCATION and BIO
+    conv_handler = ConversationHandler(
+        entry_points=[CommandHandler('start', start)],
+
+        states={
+            GENDER: [RegexHandler('^(Boy|Girl|Other)$', gender)],
+
+            PHOTO: [MessageHandler([Filters.photo], photo),
+                    CommandHandler('skip', skip_photo)],
+
+            LOCATION: [MessageHandler([Filters.location], location),
+                       CommandHandler('skip', skip_location)],
+
+            BIO: [MessageHandler([Filters.text], bio)]
+        },
+
+        fallbacks=[CommandHandler('cancel', cancel)]
+    )
+
+    dp.add_handler(conv_handler)
+
+    # log all errors
+    dp.add_error_handler(error)
+
+    # Start the Bot
+    updater.start_polling()
+
+    # Run the bot until the you presses Ctrl-C or the process receives SIGINT,
+    # SIGTERM or SIGABRT. This should be used most of the time, since
+    # start_polling() is non-blocking and will stop the bot gracefully.
+    updater.idle()
+
+
+if __name__ == '__main__':
+    main()

examples/state_machine_bot.py

@@ -1,100 +0,0 @@
-#!/usr/bin/env python
-# -*- coding: utf-8 -*-
-#
-# Basic example for a bot that awaits an answer from the user
-# This program is dedicated to the public domain under the CC0 license.
-
-import logging
-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',
-                    level=logging.INFO)
-
-# 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
-    text = update.message.text
-    chat_state = state.get(chat_id, MENU)
-    chat_context = context.get(chat_id, None)
-
-    # Since the handler will also be called on messages, we need to check if
-    # the message is actually a command
-    if chat_state == MENU and text[0] == '/':
-        state[chat_id] = AWAIT_INPUT  # set the state
-        context[chat_id] = user_id  # save the user id to context
-        bot.sendMessage(chat_id,
-                        text="Please enter your settings value or send "
-                        "/cancel to abort",
-                        reply_markup=ForceReply())
-
-    # If we are waiting for input and the right user answered
-    elif chat_state == AWAIT_INPUT and chat_context == user_id:
-        state[chat_id] = AWAIT_CONFIRMATION
-
-        # Save the user id and the answer to context
-        context[chat_id] = (user_id, update.message.text)
-        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:
-        del state[chat_id]
-        del context[chat_id]
-        if text == YES:
-            values[chat_id] = chat_context[1]
-            bot.sendMessage(chat_id, text="Changed value to %s." % values[chat_id])
-        else:
-            bot.sendMessage(chat_id,
-                            text="Value not changed: %s." % values.get(chat_id, '<not set>'))
-
-
-# Handler for the /cancel command.
-# Sets the state back to MENU and clears the context
-def cancel(bot, update):
-    chat_id = update.message.chat_id
-    del state[chat_id]
-    del context[chat_id]
-
-
-def help(bot, update):
-    bot.sendMessage(update.message.chat_id, text="Use /set to test this bot.")
-
-# Create the Updater and pass it your bot's token.
-updater = Updater("TOKEN")
-
-# The command
-updater.dispatcher.add_handler(CommandHandler('set', set_value))
-# The answer and confirmation
-updater.dispatcher.add_handler(MessageHandler([Filters.text], set_value))
-updater.dispatcher.add_handler(CommandHandler('cancel', cancel))
-updater.dispatcher.add_handler(CommandHandler('start', help))
-updater.dispatcher.add_handler(CommandHandler('help', help))
-
-# 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()

examples/timerbot.py

@@ -17,15 +17,15 @@ Press Ctrl-C on the command line or send a signal to the process to stop the
 bot.
 """
 
-from telegram.ext import Updater, CommandHandler
+from telegram.ext import Updater, CommandHandler, Job
 import logging
 
 # Enable logging
 logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-                    level=logging.INFO)
+                    level=logging.DEBUG)
 
 logger = logging.getLogger(__name__)
-job_queue = None
+timers = dict()
 
 
 # Define a few command handlers. These usually take the two arguments bot and
@@ -34,8 +34,13 @@ def start(bot, update):
     bot.sendMessage(update.message.chat_id, text='Hi! Use /set <seconds> to ' 'set a timer')
 
 
-def set(bot, update, args):
-    """ Adds a job to the queue """
+def alarm(bot, job):
+    """Function to send the alarm message"""
+    bot.sendMessage(job.context, text='Beep!')
+
+
+def set(bot, update, args, job_queue):
+    """Adds a job to the queue"""
     chat_id = update.message.chat_id
     try:
         # args[0] should contain the time for the timer in seconds
@@ -43,29 +48,38 @@ def set(bot, update, args):
         if due < 0:
             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!')
-
         # Add job to queue
-        job_queue.put(alarm, due, repeat=False)
+        job = Job(alarm, due, repeat=False, context=chat_id)
+        timers[chat_id] = job
+        job_queue.put(job)
+
         bot.sendMessage(chat_id, text='Timer successfully set!')
 
-    except IndexError:
-        bot.sendMessage(chat_id, text='Usage: /set <seconds>')
-    except ValueError:
+    except (IndexError, ValueError):
         bot.sendMessage(chat_id, text='Usage: /set <seconds>')
 
 
+def unset(bot, update):
+    """Removes the job if the user changed their mind"""
+    chat_id = update.message.chat_id
+
+    if chat_id not in timers:
+        bot.sendMessage(chat_id, text='You have no active timer')
+        return
+
+    job = timers[chat_id]
+    job.schedule_removal()
+    del timers[chat_id]
+
+    bot.sendMessage(chat_id, text='Timer successfully unset!')
+
+
 def error(bot, update, error):
     logger.warn('Update "%s" caused error "%s"' % (update, error))
 
 
 def main():
-    global job_queue
-
     updater = Updater("TOKEN")
-    job_queue = updater.job_queue
 
     # Get the dispatcher to register handlers
     dp = updater.dispatcher
@@ -73,7 +87,8 @@ def main():
     # on different commands - answer in Telegram
     dp.add_handler(CommandHandler("start", start))
     dp.add_handler(CommandHandler("help", start))
-    dp.add_handler(CommandHandler("set", set, pass_args=True))
+    dp.add_handler(CommandHandler("set", set, pass_args=True, pass_job_queue=True))
+    dp.add_handler(CommandHandler("unset", unset))
 
     # log all errors
     dp.add_error_handler(error)

requirements.txt

@@ -1,3 +1,3 @@
 future>=0.15.2
-urllib3>=1.8.3
+urllib3>=1.10
 certifi

telegram/__init__.py

@@ -80,9 +80,13 @@ from .inputvenuemessagecontent import InputVenueMessageContent
 from .inputcontactmessagecontent import InputContactMessageContent
 from .update import Update
 from .bot import Bot
+from .constants import (MAX_MESSAGE_LENGTH, MAX_CAPTION_LENGTH, SUPPORTED_WEBHOOK_PORTS,
+                        MAX_FILESIZE_DOWNLOAD, MAX_FILESIZE_UPLOAD,
+                        MAX_MESSAGES_PER_SECOND_PER_CHAT, MAX_MESSAGES_PER_SECOND,
+                        MAX_MESSAGES_PER_MINUTE_PER_GROUP)
 
 __author__ = 'devs@python-telegram-bot.org'
-__version__ = '4.3'
+__version__ = '5.0.0'
 __all__ = ['Audio', 'Bot', 'Chat', 'ChatMember', 'ChatAction', 'ChosenInlineResult',
            'CallbackQuery', 'Contact', 'Document', 'Emoji', 'File', 'ForceReply',
            'InlineKeyboardButton', 'InlineKeyboardMarkup', 'InlineQuery', 'InlineQueryResult',
@@ -99,7 +103,9 @@ __all__ = ['Audio', 'Bot', 'Chat', 'ChatMember', 'ChatAction', 'ChosenInlineResu
            'KeyboardButton', 'Location', 'Message', 'MessageEntity', 'NullHandler', 'ParseMode',
            'PhotoSize', 'ReplyKeyboardHide', 'ReplyKeyboardMarkup', 'ReplyMarkup', 'Sticker',
            'TelegramError', 'TelegramObject', 'Update', 'User', 'UserProfilePhotos', 'Venue',
-           'Video', 'Voice']
+           'Video', 'Voice', 'MAX_MESSAGE_LENGTH', 'MAX_CAPTION_LENGTH', 'SUPPORTED_WEBHOOK_PORTS',
+           'MAX_FILESIZE_DOWNLOAD', 'MAX_FILESIZE_UPLOAD', 'MAX_MESSAGES_PER_SECOND_PER_CHAT',
+           'MAX_MESSAGES_PER_SECOND', 'MAX_MESSAGES_PER_MINUTE_PER_GROUP']
 
 if version_info < (2, 7):
     from warnings import warn

telegram/__main__.py

@@ -0,0 +1,18 @@
+import sys
+
+import urllib3
+import certifi
+import future
+
+from . import __version__ as telegram_ver
+
+
+def print_ver_info():
+    print('python-telegram-bot {0}'.format(telegram_ver))
+    print('urllib3 {0}'.format(urllib3.__version__))
+    print('certifi {0}'.format(certifi.__version__))
+    print('future {0}'.format(future.__version__))
+    print('Python {0}'.format(sys.version.replace('\n', ' ')))
+
+# main
+print_ver_info()

telegram/constants.py

@@ -0,0 +1,47 @@
+# python-telegram-bot - a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# by the python-telegram-bot contributors <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/].
+"""Constants in the Telegram network.
+
+Attributes:
+    MAX_MESSAGE_LENGTH (int): from
+        https://core.telegram.org/method/messages.sendMessage#return-errors
+    MAX_CAPTION_LENGTH (int): from https://core.telegram.org/bots/api#sendphoto
+
+The following constants were extracted from the
+`Telegram Bots FAQ <https://core.telegram.org/bots/faq>`_.
+
+Attributes:
+    SUPPORTED_WEBHOOK_PORTS (List[int])
+    MAX_FILESIZE_DOWNLOAD (int): In bytes.
+    MAX_FILESIZE_UPLOAD (int): Official limit, the actual limit can be a bit higher.
+    MAX_MESSAGES_PER_SECOND_PER_CHAT (int): Telegram may allow short bursts that go over this
+        limit, but eventually you'll begin receiving 429 errors.
+    MAX_MESSAGES_PER_SECOND (int)
+    MAX_MESSAGES_PER_MINUTE_PER_GROUP (int)
+"""
+
+MAX_MESSAGE_LENGTH = 4096
+MAX_CAPTION_LENGTH = 200
+
+# constants above this line are tested
+
+SUPPORTED_WEBHOOK_PORTS = [443, 80, 88, 8443]
+MAX_FILESIZE_DOWNLOAD = int(20E6)  # (20MB)
+MAX_FILESIZE_UPLOAD = int(50E6)  # (50MB)
+MAX_MESSAGES_PER_SECOND_PER_CHAT = 1
+MAX_MESSAGES_PER_SECOND = 30
+MAX_MESSAGES_PER_MINUTE_PER_GROUP = 20

telegram/ext/__init__.py

@@ -19,7 +19,7 @@
 """Extensions over the Telegram Bot API to facilitate bot making"""
 
 from .dispatcher import Dispatcher
-from .jobqueue import JobQueue
+from .jobqueue import JobQueue, Job
 from .updater import Updater
 from .callbackqueryhandler import CallbackQueryHandler
 from .choseninlineresulthandler import ChosenInlineResultHandler
@@ -31,8 +31,9 @@ from .regexhandler import RegexHandler
 from .stringcommandhandler import StringCommandHandler
 from .stringregexhandler import StringRegexHandler
 from .typehandler import TypeHandler
+from .conversationhandler import ConversationHandler
 
-__all__ = ('Dispatcher', 'JobQueue', 'Updater', 'CallbackQueryHandler',
+__all__ = ('Dispatcher', 'JobQueue', 'Job', 'Updater', 'CallbackQueryHandler',
            'ChosenInlineResultHandler', 'CommandHandler', 'Handler', 'InlineQueryHandler',
            'MessageHandler', 'Filters', 'RegexHandler', 'StringCommandHandler',
-           'StringRegexHandler', 'TypeHandler')
+           'StringRegexHandler', 'TypeHandler', 'ConversationHandler')

telegram/ext/callbackqueryhandler.py

@@ -31,13 +31,20 @@ class CallbackQueryHandler(Handler):
         callback (function): A function that takes ``bot, update`` as
             positional arguments. It will be called when the ``check_update``
             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``
+        pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
+            instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
+             be used to insert updates. Default is ``False``.
+        pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
+            instance created by the ``Updater`` which can be used to schedule new jobs.
+            Default is ``False``.
     """
 
-    def __init__(self, callback, pass_update_queue=False):
-        super(CallbackQueryHandler, self).__init__(callback, pass_update_queue)
+    def __init__(self, callback, pass_update_queue=False, pass_job_queue=False):
+        super(CallbackQueryHandler, self).__init__(callback,
+                                                   pass_update_queue=pass_update_queue,
+                                                   pass_job_queue=pass_job_queue)
 
     def check_update(self, update):
         return isinstance(update, Update) and update.callback_query
@@ -45,7 +52,7 @@ class CallbackQueryHandler(Handler):
     def handle_update(self, update, dispatcher):
         optional_args = self.collect_optional_args(dispatcher)
 
-        self.callback(dispatcher.bot, update, **optional_args)
+        return self.callback(dispatcher.bot, update, **optional_args)
 
     # old non-PEP8 Handler methods
     m = "telegram.CallbackQueryHandler."

telegram/ext/choseninlineresulthandler.py

@@ -32,13 +32,20 @@ class ChosenInlineResultHandler(Handler):
         callback (function): A function that takes ``bot, update`` as
             positional arguments. It will be called when the ``check_update``
             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``
+        pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
+            instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
+             be used to insert updates. Default is ``False``.
+        pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
+            instance created by the ``Updater`` which can be used to schedule new jobs.
+            Default is ``False``.
     """
 
-    def __init__(self, callback, pass_update_queue=False):
-        super(ChosenInlineResultHandler, self).__init__(callback, pass_update_queue)
+    def __init__(self, callback, pass_update_queue=False, pass_job_queue=False):
+        super(ChosenInlineResultHandler, self).__init__(callback,
+                                                        pass_update_queue=pass_update_queue,
+                                                        pass_job_queue=pass_job_queue)
 
     def check_update(self, update):
         return isinstance(update, Update) and update.chosen_inline_result
@@ -46,7 +53,7 @@ class ChosenInlineResultHandler(Handler):
     def handle_update(self, update, dispatcher):
         optional_args = self.collect_optional_args(dispatcher)
 
-        self.callback(dispatcher.bot, update, **optional_args)
+        return self.callback(dispatcher.bot, update, **optional_args)
 
     # old non-PEP8 Handler methods
     m = "telegram.ChosenInlineResultHandler."

telegram/ext/commandhandler.py

@@ -40,9 +40,14 @@ class CommandHandler(Handler):
             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``
+        pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
+            instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
+             be used to insert updates. Default is ``False``.
+        pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
+            instance created by the ``Updater`` which can be used to schedule new jobs.
+            Default is ``False``.
     """
 
     def __init__(self,
@@ -50,8 +55,11 @@ class CommandHandler(Handler):
                  callback,
                  allow_edited=False,
                  pass_args=False,
-                 pass_update_queue=False):
-        super(CommandHandler, self).__init__(callback, pass_update_queue)
+                 pass_update_queue=False,
+                 pass_job_queue=False):
+        super(CommandHandler, self).__init__(callback,
+                                             pass_update_queue=pass_update_queue,
+                                             pass_job_queue=pass_job_queue)
         self.command = command
         self.allow_edited = allow_edited
         self.pass_args = pass_args
@@ -75,7 +83,7 @@ class CommandHandler(Handler):
         if self.pass_args:
             optional_args['args'] = message.text.split(' ')[1:]
 
-        self.callback(dispatcher.bot, update, **optional_args)
+        return self.callback(dispatcher.bot, update, **optional_args)
 
     # old non-PEP8 Handler methods
     m = "telegram.CommandHandler."

telegram/ext/conversationhandler.py

@@ -0,0 +1,222 @@
+#!/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 ConversationHandler """
+
+import logging
+
+from telegram import Update
+from telegram.ext import Handler
+from telegram.utils.promise import Promise
+
+
+class ConversationHandler(Handler):
+    """
+    A handler to hold a conversation with a user by managing four collections of other handlers.
+
+    The first collection, a ``list`` named ``entry_points``, is used to initiate the conversation,
+    for example with a ``CommandHandler`` or ``RegexHandler``.
+
+    The second collection, a ``dict`` named ``states``, contains the different conversation steps
+    and one or more associated handlers that should be used if the user sends a message when the
+    conversation with them is currently in that state. You will probably use mostly
+    ``MessageHandler`` and ``RegexHandler`` here.
+
+    The third collection, a ``list`` named ``fallbacks``, is used if the user is currently in a
+    conversation but the state has either no associated handler or the handler that is associated
+    to the state is inappropriate for the update, for example if the update contains a command, but
+    a regular text message is expected. You could use this for a ``/cancel`` command or to let the
+    user know their message was not recognized.
+
+    The fourth, optional collection of handlers, a ``list`` named ``timed_out_behavior`` is used if
+    the wait for ``run_async`` takes longer than defined in ``run_async_timeout``. For example,
+    you can let the user know that they should wait for a bit before they can continue.
+
+    To change the state of conversation, the callback function of a handler must return the new
+    state after responding to the user. If it does not return anything (returning ``None`` by
+    default), the state will not change. To end the conversation, the callback function must
+    return ``CallbackHandler.END`` or ``-1``.
+
+    Args:
+        entry_points (list): A list of ``Handler`` objects that can trigger the start of the
+            conversation. The first handler which ``check_update`` method returns ``True`` will be
+            used. If all return ``False``, the update is not handled.
+        states (dict): A ``dict[object: list[Handler]]`` that defines the different states of
+            conversation a user can be in and one or more associated ``Handler`` objects that
+            should be used in that state. The first handler which ``check_update`` method returns
+            ``True`` will be used.
+        fallbacks (list): A list of handlers that might be used if the user is in a conversation,
+            but every handler for their current state returned ``False`` on ``check_update``.
+            The first handler which ``check_update`` method returns ``True`` will be used. If all
+            return ``False``, the update is not handled.
+        allow_reentry (Optional[bool]): If set to ``True``, a user that is currently in a
+            conversation can restart the conversation by triggering one of the entry points.
+        run_async_timeout (Optional[float]): If the previous handler for this user was running
+            asynchronously using the ``run_async`` decorator, it might not be finished when the
+            next message arrives. This timeout defines how long the conversation handler should
+            wait for the next state to be computed. The default is ``None`` which means it will
+            wait indefinitely.
+        timed_out_behavior (Optional[list]): A list of handlers that might be used if
+            the wait for ``run_async`` timed out. The first handler which ``check_update`` method
+            returns ``True`` will be used. If all return ``False``, the update is not handled.
+
+    """
+
+    END = -1
+
+    def __init__(self,
+                 entry_points,
+                 states,
+                 fallbacks,
+                 allow_reentry=False,
+                 run_async_timeout=None,
+                 timed_out_behavior=None):
+
+        self.entry_points = entry_points
+        """:type: list[telegram.ext.Handler]"""
+
+        self.states = states
+        """:type: dict[str: telegram.ext.Handler]"""
+
+        self.fallbacks = fallbacks
+        """:type: list[telegram.ext.Handler]"""
+
+        self.allow_reentry = allow_reentry
+        self.run_async_timeout = run_async_timeout
+
+        self.timed_out_behavior = timed_out_behavior
+        """:type: list[telegram.ext.Handler]"""
+
+        self.conversations = dict()
+        """:type: dict[(int, int): str]"""
+
+        self.current_conversation = None
+        self.current_handler = None
+
+        self.logger = logging.getLogger(__name__)
+
+    def check_update(self, update):
+
+        if not isinstance(update, Update):
+            return False
+
+        user = None
+        chat = None
+
+        if update.message:
+            user = update.message.from_user
+            chat = update.message.chat
+
+        elif update.edited_message:
+            user = update.edited_message.from_user
+            chat = update.edited_message.chat
+
+        elif update.inline_query:
+            user = update.inline_query.from_user
+
+        elif update.chosen_inline_result:
+            user = update.chosen_inline_result.from_user
+
+        elif update.callback_query:
+            user = update.callback_query.from_user
+            chat = update.callback_query.message.chat if update.callback_query.message else None
+
+        else:
+            return False
+
+        key = (chat.id, user.id) if chat else (None, user.id)
+        state = self.conversations.get(key)
+
+        # Resolve promises
+        if isinstance(state, tuple) and len(state) is 2 and isinstance(state[1], Promise):
+            self.logger.debug('waiting for promise...')
+
+            old_state, new_state = state
+            new_state.result(timeout=self.run_async_timeout)
+
+            if new_state.done.is_set():
+                self.update_state(new_state.result(), key)
+                state = self.conversations.get(key)
+
+            else:
+                for candidate in (self.timed_out_behavior or []):
+                    if candidate.check_update(update):
+                        # Save the current user and the selected handler for handle_update
+                        self.current_conversation = key
+                        self.current_handler = candidate
+
+                        return True
+
+                else:
+                    return False
+
+        self.logger.debug('selecting conversation %s with state %s' % (str(key), str(state)))
+
+        handler = None
+
+        # Search entry points for a match
+        if state is None or self.allow_reentry:
+            for entry_point in self.entry_points:
+                if entry_point.check_update(update):
+                    handler = entry_point
+                    break
+
+            else:
+                if state is None:
+                    return False
+
+        # Get the handler list for current state, if we didn't find one yet and we're still here
+        if state is not None and not handler:
+            handlers = self.states.get(state)
+
+            for candidate in (handlers or []):
+                if candidate.check_update(update):
+                    handler = candidate
+                    break
+
+            # Find a fallback handler if all other handlers fail
+            else:
+                for fallback in self.fallbacks:
+                    if fallback.check_update(update):
+                        handler = fallback
+                        break
+
+                else:
+                    return False
+
+        # Save the current user and the selected handler for handle_update
+        self.current_conversation = key
+        self.current_handler = handler
+
+        return True
+
+    def handle_update(self, update, dispatcher):
+
+        new_state = self.current_handler.handle_update(update, dispatcher)
+
+        self.update_state(new_state, self.current_conversation)
+
+    def update_state(self, new_state, key):
+        if new_state == self.END:
+            del self.conversations[key]
+
+        elif isinstance(new_state, Promise):
+            self.conversations[key] = (self.conversations[key], new_state)
+
+        elif new_state is not None:
+            self.conversations[key] = new_state

telegram/ext/dispatcher.py

@@ -30,6 +30,7 @@ from telegram import (TelegramError, NullHandler)
 from telegram.utils import request
 from telegram.ext.handler import Handler
 from telegram.utils.deprecate import deprecate
+from telegram.utils.promise import Promise
 
 logging.getLogger(__name__).addHandler(NullHandler())
 
@@ -45,17 +46,16 @@ def _pooled():
     A wrapper to run a thread in a thread pool
     """
     while 1:
-        try:
-            func, args, kwargs = ASYNC_QUEUE.get()
+        promise = ASYNC_QUEUE.get()
 
         # If unpacking fails, the thread pool is being closed from Updater._join_async_threads
-        except TypeError:
+        if not isinstance(promise, Promise):
             logging.getLogger(__name__).debug("Closing run_async thread %s/%d" %
                                               (current_thread().getName(), len(ASYNC_THREADS)))
             break
 
         try:
-            func(*args, **kwargs)
+            promise.run()
 
         except:
             logging.getLogger(__name__).exception("run_async function raised exception")
@@ -80,7 +80,9 @@ def run_async(func):
         """
         A wrapper to run a function in a thread
         """
-        ASYNC_QUEUE.put((func, args, kwargs))
+        promise = Promise(func, args, kwargs)
+        ASYNC_QUEUE.put(promise)
+        return promise
 
     return async_func
 
@@ -94,11 +96,16 @@ class Dispatcher(object):
             handlers
         update_queue (Queue): The synchronized queue that will contain the
             updates.
+        job_queue (Optional[telegram.ext.JobQueue]): The ``JobQueue`` instance to pass onto handler
+            callbacks
+        workers (Optional[int]): Number of maximum concurrent worker threads for the ``@run_async``
+            decorator
     """
 
-    def __init__(self, bot, update_queue, workers=4, exception_event=None):
+    def __init__(self, bot, update_queue, workers=4, exception_event=None, job_queue=None):
         self.bot = bot
         self.update_queue = update_queue
+        self.job_queue = job_queue
 
         self.handlers = {}
         """:type: dict[int, list[Handler]"""
@@ -116,6 +123,11 @@ class Dispatcher(object):
                 if request.is_con_pool_initialized():
                     raise RuntimeError('Connection Pool already initialized')
 
+                # we need a connection pool the size of:
+                # * for each of the workers
+                # * 1 for Dispatcher
+                # * 1 for polling Updater (even if updater is webhook, we can spare a connection)
+                # * 1 for JobQueue
                 request.CON_POOL_SIZE = workers + 3
                 for i in range(workers):
                     thread = Thread(target=_pooled, name=str(i))

telegram/ext/handler.py

@@ -31,14 +31,20 @@ class Handler(object):
         callback (function): A function that takes ``bot, update`` as
             positional arguments. It will be called when the ``check_update``
             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``
+        pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
+            instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
+             be used to insert updates. Default is ``False``.
+        pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
+            instance created by the ``Updater`` which can be used to schedule new jobs.
+            Default is ``False``.
     """
 
-    def __init__(self, callback, pass_update_queue=False):
+    def __init__(self, callback, pass_update_queue=False, pass_job_queue=False):
         self.callback = callback
         self.pass_update_queue = pass_update_queue
+        self.pass_job_queue = pass_job_queue
 
     def check_update(self, update):
         """
@@ -57,11 +63,13 @@ class Handler(object):
         """
         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.
+        cases call ``self.callback(dispatcher.bot, update)``, possibly along with
+        optional arguments. To work with the ``ConversationHandler``, this method should return the
+        value returned from ``self.callback``
 
         Args:
             update (object): The update to be handled
+            dispatcher (Dispatcher): The dispatcher to collect optional args
 
         """
         raise NotImplementedError
@@ -77,6 +85,8 @@ class Handler(object):
         optional_args = dict()
         if self.pass_update_queue:
             optional_args['update_queue'] = dispatcher.update_queue
+        if self.pass_job_queue:
+            optional_args['job_queue'] = dispatcher.job_queue
 
         return optional_args
 

telegram/ext/inlinequeryhandler.py

@@ -31,13 +31,20 @@ class InlineQueryHandler(Handler):
         callback (function): A function that takes ``bot, update`` as
             positional arguments. It will be called when the ``check_update``
             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``
+        pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
+            instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
+             be used to insert updates. Default is ``False``.
+        pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
+            instance created by the ``Updater`` which can be used to schedule new jobs.
+            Default is ``False``.
     """
 
-    def __init__(self, callback, pass_update_queue=False):
-        super(InlineQueryHandler, self).__init__(callback, pass_update_queue)
+    def __init__(self, callback, pass_update_queue=False, pass_job_queue=False):
+        super(InlineQueryHandler, self).__init__(callback,
+                                                 pass_update_queue=pass_update_queue,
+                                                 pass_job_queue=pass_job_queue)
 
     def check_update(self, update):
         return isinstance(update, Update) and update.inline_query
@@ -45,7 +52,7 @@ class InlineQueryHandler(Handler):
     def handle_update(self, update, dispatcher):
         optional_args = self.collect_optional_args(dispatcher)
 
-        self.callback(dispatcher.bot, update, **optional_args)
+        return self.callback(dispatcher.bot, update, **optional_args)
 
     # old non-PEP8 Handler methods
     m = "telegram.InlineQueryHandler."

telegram/ext/jobqueue.py

@@ -16,139 +16,240 @@
 #
 # 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 class JobQueue."""
+"""This module contains the classes JobQueue and Job."""
 
 import logging
 import time
-from threading import Thread, Lock
-from queue import PriorityQueue
+from threading import Thread, Lock, Event
+from queue import PriorityQueue, Empty
 
 
 class JobQueue(object):
-    """
-    This class allows you to periodically perform tasks with the bot.
+    """This class allows you to periodically perform tasks with the bot.
 
     Attributes:
-        tick_interval (float):
         queue (PriorityQueue):
         bot (Bot):
-        running (bool):
+        prevent_autostart (Optional[bool]): If ``True``, the job queue will not be started
+                automatically. Defaults to ``False``
 
     Args:
         bot (Bot): The bot instance that should be passed to the jobs
-        tick_interval (Optional[float]): The interval this queue should check
-            the newest task in seconds. Defaults to 1.0
 
     """
 
-    def __init__(self, bot, tick_interval=1.0):
-        self.tick_interval = tick_interval
+    def __init__(self, bot, prevent_autostart=False):
         self.queue = PriorityQueue()
         self.bot = bot
-        self.logger = logging.getLogger(__name__)
-        self.__lock = Lock()
-        self.running = False
+        self.logger = logging.getLogger(self.__class__.__name__)
+        self.__start_lock = Lock()
+        self.__next_peek_lock = Lock()  # to protect self._next_peek & self.__tick
+        self.__tick = Event()
+        self.__thread = None
+        """:type: Thread"""
+        self._next_peek = None
+        """:type: float"""
+        self._running = False
 
-    def put(self, run, interval, repeat=True, next_t=None, prevent_autostart=False):
-        """
-        Queue a new job. If the JobQueue is not running, it will be started.
+        if not prevent_autostart:
+            self.logger.debug('Auto-starting %s', self.__class__.__name__)
+            self.start()
+
+    def put(self, job, next_t=None):
+        """Queue a new job. If the JobQueue is not running, it will be started.
 
         Args:
-            run (function): A function that takes the parameter `bot`
-            interval (float): The interval in seconds in which `run` should be
-                executed
-            repeat (Optional[bool]): If `False`, job will only be executed once
-            next_t (Optional[float]): Time in seconds in which run should be
-                executed first. Defaults to `interval`
-            prevent_autostart (Optional[bool]): If `True`, the job queue will
-                not be started automatically if it is not running.
-        """
-        name = run.__name__
+            job (Job): The ``Job`` instance representing the new job
+            next_t (Optional[float]): Time in seconds in which the job should be executed first.
+                Defaults to ``job.interval``
 
-        job = JobQueue.Job()
-        job.run = run
-        job.interval = interval
-        job.name = name
-        job.repeat = repeat
+        """
+        job.job_queue = self
 
         if next_t is None:
-            next_t = interval
+            next_t = job.interval
 
-        next_t += time.time()
+        now = time.time()
+        next_t += now
 
-        self.logger.debug('Putting a %s with t=%f' % (job.name, next_t))
+        self.logger.debug('Putting job %s with t=%f', job.name, next_t)
         self.queue.put((next_t, job))
 
-        if not self.running and not prevent_autostart:
-            self.logger.debug('Auto-starting JobQueue')
-            self.start()
+        # Wake up the loop if this job should be executed next
+        self._set_next_peek(next_t)
+
+    def _set_next_peek(self, t):
+        """
+        Set next peek if not defined or `t` is before next peek.
+        In case the next peek was set, also trigger the `self.__tick` event.
+
+        """
+        with self.__next_peek_lock:
+            if not self._next_peek or self._next_peek > t:
+                self._next_peek = t
+                self.__tick.set()
 
     def tick(self):
         """
-        Run all jobs that are due and re-enqueue them with their interval
+        Run all jobs that are due and re-enqueue them with their interval.
+
         """
         now = time.time()
 
-        self.logger.debug('Ticking jobs with t=%f' % now)
-        while not self.queue.empty():
-            t, j = self.queue.queue[0]
-            self.logger.debug('Peeked at %s with t=%f' % (j.name, t))
+        self.logger.debug('Ticking jobs with t=%f', now)
 
-            if t < now:
-                self.queue.get()
-                self.logger.debug('Running job %s' % j.name)
-                try:
-                    j.run(self.bot)
-                except:
-                    self.logger.exception('An uncaught error was raised while '
-                                          'executing job %s' % j.name)
-                if j.repeat:
-                    self.put(j.run, j.interval)
+        while True:
+            try:
+                t, job = self.queue.get(False)
+            except Empty:
+                break
+
+            self.logger.debug('Peeked at %s with t=%f', job.name, t)
+
+            if t > now:
+                # we can get here in two conditions:
+                # 1. At the second or later pass of the while loop, after we've already processed
+                #    the job(s) we were supposed to at this time.
+                # 2. At the first iteration of the loop only if `self.put()` had triggered
+                #    `self.__tick` because `self._next_peek` wasn't set
+                self.logger.debug("Next task isn't due yet. Finished!")
+                self.queue.put((t, job))
+                self._set_next_peek(t)
+                break
+
+            if job._remove.is_set():
+                self.logger.debug('Removing job %s', job.name)
                 continue
 
-            self.logger.debug('Next task isn\'t due yet. Finished!')
-            break
+            if job.enabled:
+                self.logger.debug('Running job %s', job.name)
+
+                try:
+                    job.run(self.bot)
+
+                except:
+                    self.logger.exception('An uncaught error was raised while executing job %s',
+                                          job.name)
+
+            else:
+                self.logger.debug('Skipping disabled job %s', job.name)
+
+            if job.repeat:
+                self.put(job)
 
     def start(self):
         """
         Starts the job_queue thread.
+
         """
-        self.__lock.acquire()
-        if not self.running:
-            self.running = True
-            self.__lock.release()
-            job_queue_thread = Thread(target=self._start, name="job_queue")
-            job_queue_thread.start()
-            self.logger.debug('Job Queue thread started')
+        self.__start_lock.acquire()
+
+        if not self._running:
+            self._running = True
+            self.__start_lock.release()
+            self.__thread = Thread(target=self._main_loop, name="job_queue")
+            self.__thread.start()
+            self.logger.debug('%s thread started', self.__class__.__name__)
+
         else:
-            self.__lock.release()
+            self.__start_lock.release()
 
-    def _start(self):
+    def _main_loop(self):
         """
-        Thread target of thread 'job_queue'. Runs in background and performs
-        ticks on the job queue.
+        Thread target of thread ``job_queue``. Runs in background and performs ticks on the job
+        queue.
+
         """
-        while self.running:
+        while self._running:
+            # self._next_peek may be (re)scheduled during self.tick() or self.put()
+            with self.__next_peek_lock:
+                tmout = self._next_peek and self._next_peek - time.time()
+                self._next_peek = None
+                self.__tick.clear()
+
+            self.__tick.wait(tmout)
+
+            # If we were woken up by self.stop(), just bail out
+            if not self._running:
+                break
+
             self.tick()
-            time.sleep(self.tick_interval)
 
-        self.logger.debug('Job Queue thread stopped')
+        self.logger.debug('%s thread stopped', self.__class__.__name__)
 
     def stop(self):
         """
         Stops the thread
         """
-        with self.__lock:
-            self.running = False
+        with self.__start_lock:
+            self._running = False
 
-    class Job(object):
-        """ Inner class that represents a job """
-        interval = None
-        name = None
-        repeat = None
+        self.__tick.set()
+        if self.__thread is not None:
+            self.__thread.join()
 
-        def run(self):
-            pass
+    def jobs(self):
+        """Returns a tuple of all jobs that are currently in the ``JobQueue``"""
+        return tuple(job[1] for job in self.queue.queue if job)
 
-        def __lt__(self, other):
-            return False
+
+class Job(object):
+    """This class encapsulates a Job
+
+    Attributes:
+        callback (function):
+        interval (float):
+        repeat (bool):
+        name (str):
+        enabled (bool): Boolean property that decides if this job is currently active
+
+    Args:
+        callback (function): The callback function that should be executed by the Job. It should
+            take two parameters ``bot`` and ``job``, where ``job`` is the ``Job`` instance. It
+            can be used to terminate the job or modify its interval.
+        interval (float): The interval in which this job should execute its callback function in
+            seconds.
+        repeat (Optional[bool]): If this job should be periodically execute its callback function
+            (``True``) or only once (``False``). Defaults to ``True``
+        context (Optional[object]): Additional data needed for the callback function. Can be
+            accessed through ``job.context`` in the callback. Defaults to ``None``
+
+    """
+    job_queue = None
+
+    def __init__(self, callback, interval, repeat=True, context=None):
+        self.callback = callback
+        self.interval = interval
+        self.repeat = repeat
+        self.context = context
+
+        self.name = callback.__name__
+        self._remove = Event()
+        self._enabled = Event()
+        self._enabled.set()
+
+    def run(self, bot):
+        """Executes the callback function"""
+        self.callback(bot, self)
+
+    def schedule_removal(self):
+        """
+        Schedules this job for removal from the ``JobQueue``. It will be removed without executing
+        its callback function again.
+
+        """
+        self._remove.set()
+
+    def is_enabled(self):
+        return self._enabled.is_set()
+
+    def set_enabled(self, status):
+        if status:
+            self._enabled.set()
+        else:
+            self._enabled.clear()
+
+    enabled = property(is_enabled, set_enabled)
+
+    def __lt__(self, other):
+        return False

telegram/ext/messagehandler.py

@@ -105,8 +105,15 @@ class MessageHandler(Handler):
             be used to insert updates. Default is ``False``
     """
 
-    def __init__(self, filters, callback, allow_edited=False, pass_update_queue=False):
-        super(MessageHandler, self).__init__(callback, pass_update_queue)
+    def __init__(self,
+                 filters,
+                 callback,
+                 allow_edited=False,
+                 pass_update_queue=False,
+                 pass_job_queue=False):
+        super(MessageHandler, self).__init__(callback,
+                                             pass_update_queue=pass_update_queue,
+                                             pass_job_queue=pass_job_queue)
         self.filters = filters
         self.allow_edited = allow_edited
 
@@ -129,7 +136,7 @@ class MessageHandler(Handler):
     def handle_update(self, update, dispatcher):
         optional_args = self.collect_optional_args(dispatcher)
 
-        self.callback(dispatcher.bot, update, **optional_args)
+        return self.callback(dispatcher.bot, update, **optional_args)
 
     # old non-PEP8 Handler methods
     m = "telegram.MessageHandler."

telegram/ext/regexhandler.py

@@ -45,9 +45,14 @@ class RegexHandler(Handler):
         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``
+        pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
+            instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
+             be used to insert updates. Default is ``False``.
+        pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
+            instance created by the ``Updater`` which can be used to schedule new jobs.
+            Default is ``False``.
     """
 
     def __init__(self,
@@ -55,8 +60,11 @@ class RegexHandler(Handler):
                  callback,
                  pass_groups=False,
                  pass_groupdict=False,
-                 pass_update_queue=False):
-        super(RegexHandler, self).__init__(callback, pass_update_queue)
+                 pass_update_queue=False,
+                 pass_job_queue=False):
+        super(RegexHandler, self).__init__(callback,
+                                           pass_update_queue=pass_update_queue,
+                                           pass_job_queue=pass_job_queue)
 
         if isinstance(pattern, string_types):
             pattern = re.compile(pattern)
@@ -81,7 +89,7 @@ class RegexHandler(Handler):
         if self.pass_groupdict:
             optional_args['groupdict'] = match.groupdict()
 
-        self.callback(dispatcher.bot, update, **optional_args)
+        return self.callback(dispatcher.bot, update, **optional_args)
 
     # old non-PEP8 Handler methods
     m = "telegram.RegexHandler."

telegram/ext/stringcommandhandler.py

@@ -36,13 +36,25 @@ class StringCommandHandler(Handler):
             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``
+        pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
+            instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
+             be used to insert updates. Default is ``False``.
+        pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
+            instance created by the ``Updater`` which can be used to schedule new jobs.
+            Default is ``False``.
     """
 
-    def __init__(self, command, callback, pass_args=False, pass_update_queue=False):
-        super(StringCommandHandler, self).__init__(callback, pass_update_queue)
+    def __init__(self,
+                 command,
+                 callback,
+                 pass_args=False,
+                 pass_update_queue=False,
+                 pass_job_queue=False):
+        super(StringCommandHandler, self).__init__(callback,
+                                                   pass_update_queue=pass_update_queue,
+                                                   pass_job_queue=pass_job_queue)
         self.command = command
         self.pass_args = pass_args
 
@@ -56,7 +68,7 @@ class StringCommandHandler(Handler):
         if self.pass_args:
             optional_args['args'] = update.split(' ')[1:]
 
-        self.callback(dispatcher.bot, update, **optional_args)
+        return self.callback(dispatcher.bot, update, **optional_args)
 
     # old non-PEP8 Handler methods
     m = "telegram.StringCommandHandler."

telegram/ext/stringregexhandler.py

@@ -44,9 +44,14 @@ class StringRegexHandler(Handler):
         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``
+        pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
+            instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
+             be used to insert updates. Default is ``False``.
+        pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
+            instance created by the ``Updater`` which can be used to schedule new jobs.
+            Default is ``False``.
     """
 
     def __init__(self,
@@ -54,8 +59,11 @@ class StringRegexHandler(Handler):
                  callback,
                  pass_groups=False,
                  pass_groupdict=False,
-                 pass_update_queue=False):
-        super(StringRegexHandler, self).__init__(callback, pass_update_queue)
+                 pass_update_queue=False,
+                 pass_job_queue=False):
+        super(StringRegexHandler, self).__init__(callback,
+                                                 pass_update_queue=pass_update_queue,
+                                                 pass_job_queue=pass_job_queue)
 
         if isinstance(pattern, string_types):
             pattern = re.compile(pattern)
@@ -76,7 +84,7 @@ class StringRegexHandler(Handler):
         if self.pass_groupdict:
             optional_args['groupdict'] = match.groupdict()
 
-        self.callback(dispatcher.bot, update, **optional_args)
+        return self.callback(dispatcher.bot, update, **optional_args)
 
     # old non-PEP8 Handler methods
     m = "telegram.StringRegexHandler."

telegram/ext/typehandler.py

@@ -34,13 +34,25 @@ class TypeHandler(Handler):
             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``
+        pass_update_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``update_queue`` will be passed to the callback function. It will be the ``Queue``
+            instance used by the ``Updater`` and ``Dispatcher`` that contains new updates which can
+             be used to insert updates. Default is ``False``.
+        pass_job_queue (optional[bool]): If set to ``True``, a keyword argument called
+            ``job_queue`` will be passed to the callback function. It will be a ``JobQueue``
+            instance created by the ``Updater`` which can be used to schedule new jobs.
+            Default is ``False``.
     """
 
-    def __init__(self, type, callback, strict=False, pass_update_queue=False):
-        super(TypeHandler, self).__init__(callback, pass_update_queue)
+    def __init__(self,
+                 type,
+                 callback,
+                 strict=False,
+                 pass_update_queue=False,
+                 pass_job_queue=False):
+        super(TypeHandler, self).__init__(callback,
+                                          pass_update_queue=pass_update_queue,
+                                          pass_job_queue=pass_job_queue)
         self.type = type
         self.strict = strict
 
@@ -53,7 +65,7 @@ class TypeHandler(Handler):
     def handle_update(self, update, dispatcher):
         optional_args = self.collect_optional_args(dispatcher)
 
-        self.callback(dispatcher.bot, update, **optional_args)
+        return self.callback(dispatcher.bot, update, **optional_args)
 
     # old non-PEP8 Handler methods
     m = "telegram.TypeHandler."

telegram/ext/updater.py

@@ -65,12 +65,7 @@ class Updater(object):
         ValueError: If both `token` and `bot` are passed or none of them.
     """
 
-    def __init__(self,
-                 token=None,
-                 base_url=None,
-                 workers=4,
-                 bot=None,
-                 job_queue_tick_interval=1.0):
+    def __init__(self, token=None, base_url=None, workers=4, bot=None):
         if (token is None) and (bot is None):
             raise ValueError('`token` or `bot` must be passed')
         if (token is not None) and (bot is not None):
@@ -81,9 +76,13 @@ class Updater(object):
         else:
             self.bot = Bot(token, base_url)
         self.update_queue = Queue()
-        self.job_queue = JobQueue(self.bot, job_queue_tick_interval)
+        self.job_queue = JobQueue(self.bot)
         self.__exception_event = Event()
-        self.dispatcher = Dispatcher(self.bot, self.update_queue, workers, self.__exception_event)
+        self.dispatcher = Dispatcher(self.bot,
+                                     self.update_queue,
+                                     job_queue=self.job_queue,
+                                     workers=workers,
+                                     exception_event=self.__exception_event)
         self.last_update_id = 0
         self.logger = logging.getLogger(__name__)
         self.running = False

telegram/utils/promise.py

@@ -0,0 +1,46 @@
+#!/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 Promise class """
+
+from threading import Event
+
+
+class Promise(object):
+    """A simple Promise implementation for the run_async decorator"""
+
+    def __init__(self, pooled_function, args, kwargs):
+        self.pooled_function = pooled_function
+        self.args = args
+        self.kwargs = kwargs
+        self.done = Event()
+        self._result = None
+
+    def run(self):
+        try:
+            self._result = self.pooled_function(*self.args, **self.kwargs)
+
+        except:
+            raise
+
+        finally:
+            self.done.set()
+
+    def result(self, timeout=None):
+        self.done.wait(timeout=timeout)
+        return self._result

telegram/utils/request.py

@@ -19,6 +19,7 @@
 """This module contains methods to make POST and GET requests"""
 
 import json
+import os
 import socket
 import logging
 
@@ -31,26 +32,44 @@ from telegram.error import Unauthorized, NetworkError, TimedOut, BadRequest
 
 _CON_POOL = None
 """:type: urllib3.PoolManager"""
+_CON_POOL_PROXY = None
+_CON_POOL_PROXY_KWARGS = {}
 CON_POOL_SIZE = 1
 
 logging.getLogger('urllib3').setLevel(logging.WARNING)
 
 
 def _get_con_pool():
-    global _CON_POOL
-
     if _CON_POOL is not None:
         return _CON_POOL
 
-    _CON_POOL = urllib3.PoolManager(maxsize=CON_POOL_SIZE,
-                                    cert_reqs='CERT_REQUIRED',
-                                    ca_certs=certifi.where(),
-                                    socket_options=HTTPConnection.default_socket_options + [
-                                        (socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1),
-                                    ])
+    _init_con_pool()
     return _CON_POOL
 
 
+def _init_con_pool():
+    global _CON_POOL
+    kwargs = dict(maxsize=CON_POOL_SIZE,
+                  cert_reqs='CERT_REQUIRED',
+                  ca_certs=certifi.where(),
+                  socket_options=HTTPConnection.default_socket_options + [
+                      (socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1),
+                  ])
+    proxy_url = _get_con_pool_proxy()
+    if not proxy_url:
+        mgr = urllib3.PoolManager(**kwargs)
+    else:
+        if _CON_POOL_PROXY_KWARGS:
+            kwargs.update(_CON_POOL_PROXY_KWARGS)
+        mgr = urllib3.proxy_from_url(proxy_url, **kwargs)
+        if mgr.proxy.auth:
+            # TODO: what about other auth types?
+            auth_hdrs = urllib3.make_headers(proxy_basic_auth=mgr.proxy.auth)
+            mgr.proxy_headers.update(auth_hdrs)
+
+    _CON_POOL = mgr
+
+
 def is_con_pool_initialized():
     return _CON_POOL is not None
 
@@ -62,6 +81,47 @@ def stop_con_pool():
         _CON_POOL = None
 
 
+def set_con_pool_proxy(url, **urllib3_kwargs):
+    """Setup connection pool behind a proxy
+
+    Args:
+        url (str): The URL to the proxy server. For example: `http://127.0.0.1:3128`
+        urllib3_kwargs (dict): Arbitrary arguments passed as-is to `urllib3.ProxyManager`
+
+    """
+    global _CON_POOL_PROXY
+    global _CON_POOL_PROXY_KWARGS
+
+    if is_con_pool_initialized():
+        raise TelegramError('conpool already initialized')
+
+    _CON_POOL_PROXY = url
+    _CON_POOL_PROXY_KWARGS = urllib3_kwargs
+
+
+def _get_con_pool_proxy():
+    """Return the user configured proxy according to the following order:
+
+      * proxy configured using `set_con_pool_proxy()`.
+      * proxy set in `HTTPS_PROXY` env. var.
+      * proxy set in `https_proxy` env. var.
+      * None (if no proxy is configured)
+
+      Returns:
+          str | None
+
+    """
+    if _CON_POOL_PROXY:
+        return _CON_POOL_PROXY
+    from_env = os.environ.get('HTTPS_PROXY')
+    if from_env:
+        return from_env
+    from_env = os.environ.get('https_proxy')
+    if from_env:
+        return from_env
+    return None
+
+
 def _parse(json_data):
     """Try and parse the JSON returned from Telegram.
 
@@ -171,7 +231,8 @@ def post(url, data, timeout=None):
         result = _request_wrapper('POST',
                                   url,
                                   body=data.encode(),
-                                  headers={'Content-Type': 'application/json'})
+                                  headers={'Content-Type': 'application/json'},
+                                  **urlopen_kwargs)
 
     return _parse(result)
 

telegram/utils/webhookhandler.py

@@ -102,3 +102,19 @@ class WebhookHandler(BaseHTTPServer.BaseHTTPRequestHandler, object):
         if clen < 0:
             raise _InvalidPost(403)
         return clen
+
+    def log_message(self, format, *args):
+        """Log an arbitrary message.
+
+        This is used by all other logging functions.
+
+        It overrides ``BaseHTTPRequestHandler.log_message``, which logs to ``sys.stderr``.
+
+        The first argument, FORMAT, is a format string for the message to be logged.  If the format
+        string contains any % escapes requiring parameters, they should be specified as subsequent
+        arguments (it's just like printf!).
+
+        The client ip is prefixed to every message.
+        """
+
+        self.logger.debug("%s - - %s" % (self.address_string(), format % args))

tests/test_constants.py

@@ -0,0 +1,69 @@
+# python-telegram-bot - a Python interface to the Telegram Bot API
+# Copyright (C) 2015-2016
+# by the python-telegram-bot contributors <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/].
+"""Test the Telegram constants."""
+
+import sys
+
+from flaky import flaky
+
+if sys.version_info[0:2] == (2, 6):
+    import unittest2 as unittest
+else:
+    import unittest
+
+sys.path.append('.')
+
+import telegram
+from telegram.error import BadRequest
+from tests.base import BaseTest, timeout
+
+
+class ConstantsTest(BaseTest, unittest.TestCase):
+
+    @flaky(3, 1)
+    @timeout(10)
+    def testMaxMessageLength(self):
+        self._bot.sendMessage(chat_id=self._chat_id,
+                              text='a' * telegram.constants.MAX_MESSAGE_LENGTH)
+
+        try:
+            self._bot.sendMessage(chat_id=self._chat_id,
+                                  text='a' * (telegram.constants.MAX_MESSAGE_LENGTH + 1))
+        except BadRequest as e:
+            err = str(e)
+
+        self.assertTrue("too long" in err)  # BadRequest: 'Message is too long'
+
+    @flaky(3, 1)
+    @timeout(10)
+    def testMaxCaptionLength(self):
+        self._bot.sendPhoto(photo=open('tests/data/telegram.png', 'rb'),
+                            caption='a' * telegram.constants.MAX_CAPTION_LENGTH,
+                            chat_id=self._chat_id)
+
+        try:
+            self._bot.sendPhoto(photo=open('tests/data/telegram.png', 'rb'),
+                                caption='a' * (telegram.constants.MAX_CAPTION_LENGTH + 1),
+                                chat_id=self._chat_id)
+        except BadRequest as e:
+            err = str(e)
+
+        self.assertTrue("TOO_LONG" in err)  # BadRequest: 'MEDIA_CAPTION_TOO_LONG'
+
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_conversationhandler.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python
+# encoding: utf-8
+#
+# 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 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 ConversationHandler
+"""
+import logging
+import sys
+from time import sleep
+
+if sys.version_info[0:2] == (2, 6):
+    import unittest2 as unittest
+else:
+    import unittest
+
+try:
+    # python2
+    from urllib2 import urlopen, Request, HTTPError
+except ImportError:
+    # python3
+    from urllib.request import Request, urlopen
+    from urllib.error import HTTPError
+
+sys.path.append('.')
+
+from telegram import Update, Message, TelegramError, User, Chat, Bot
+from telegram.utils.request import stop_con_pool
+from telegram.ext import *
+from tests.base import BaseTest
+from tests.test_updater import MockBot
+
+# Enable logging
+root = logging.getLogger()
+root.setLevel(logging.DEBUG)
+
+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 ConversationHandlerTest(BaseTest, unittest.TestCase):
+    """
+    This object represents the tests for the conversation handler.
+    """
+
+    # State definitions
+    # At first we're thirsty.  Then we brew coffee, we drink it
+    # and then we can start coding!
+    END, THIRSTY, BREWING, DRINKING, CODING = range(-1, 4)
+
+    # Test related
+    def setUp(self):
+        self.updater = None
+        self.current_state = dict()
+        self.entry_points = [CommandHandler('start', self.start)]
+        self.states = {self.THIRSTY: [CommandHandler('brew', self.brew),
+                                      CommandHandler('wait', self.start)],
+                       self.BREWING: [CommandHandler('pourCoffee', self.drink)],
+                       self.DRINKING: [CommandHandler('startCoding', self.code),
+                                       CommandHandler('drinkMore', self.drink)],
+                       self.CODING: [CommandHandler('keepCoding', self.code),
+                                     CommandHandler('gettingThirsty', self.start),
+                                     CommandHandler('drinkMore', self.drink)],}
+        self.fallbacks = [CommandHandler('eat', self.start)]
+
+    def _setup_updater(self, *args, **kwargs):
+        stop_con_pool()
+        bot = MockBot(*args, **kwargs)
+        self.updater = Updater(workers=2, bot=bot)
+
+    def tearDown(self):
+        if self.updater is not None:
+            self.updater.stop()
+        stop_con_pool()
+
+    def reset(self):
+        self.current_state = dict()
+
+    # State handlers
+    def _set_state(self, update, state):
+        self.current_state[update.message.from_user.id] = state
+        return state
+
+    def _get_state(self, user_id):
+        return self.current_state[user_id]
+
+    # Actions
+    def start(self, bot, update):
+        return self._set_state(update, self.THIRSTY)
+
+    def brew(self, bot, update):
+        return self._set_state(update, self.BREWING)
+
+    def drink(self, bot, update):
+        return self._set_state(update, self.DRINKING)
+
+    def code(self, bot, update):
+        return self._set_state(update, self.CODING)
+
+    # Tests
+    def test_addConversationHandler(self):
+        self._setup_updater('', messages=0)
+        d = self.updater.dispatcher
+        user = User(first_name="Misses Test", id=123)
+        second_user = User(first_name="Mister Test", id=124)
+
+        handler = ConversationHandler(entry_points=self.entry_points,
+                                      states=self.states,
+                                      fallbacks=self.fallbacks)
+        d.add_handler(handler)
+        queue = self.updater.start_polling(0.01)
+
+        # User one, starts the state machine.
+        message = Message(0, user, None, None, text="/start")
+        queue.put(Update(update_id=0, message=message))
+        sleep(.1)
+        self.assertTrue(self.current_state[user.id] == self.THIRSTY)
+
+        # The user is thirsty and wants to brew coffee.
+        message = Message(0, user, None, None, text="/brew")
+        queue.put(Update(update_id=0, message=message))
+        sleep(.1)
+        self.assertTrue(self.current_state[user.id] == self.BREWING)
+
+        # Lets see if an invalid command makes sure, no state is changed.
+        message = Message(0, user, None, None, text="/nothing")
+        queue.put(Update(update_id=0, message=message))
+        sleep(.1)
+        self.assertTrue(self.current_state[user.id] == self.BREWING)
+
+        # Lets see if the state machine still works by pouring coffee.
+        message = Message(0, user, None, None, text="/pourCoffee")
+        queue.put(Update(update_id=0, message=message))
+        sleep(.1)
+        self.assertTrue(self.current_state[user.id] == self.DRINKING)
+
+        # Let's now verify that for another user, who did not start yet,
+        # the state has not been changed.
+        message = Message(0, second_user, None, None, text="/brew")
+        queue.put(Update(update_id=0, message=message))
+        sleep(.1)
+        self.assertRaises(KeyError, self._get_state, user_id=second_user.id)
+
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_jobqueue.py

@@ -32,7 +32,7 @@ else:
 sys.path.append('.')
 
 from telegram.utils.request import stop_con_pool
-from telegram.ext import JobQueue, Updater
+from telegram.ext import JobQueue, Job, Updater
 from tests.base import BaseTest
 
 # Enable logging
@@ -53,7 +53,7 @@ class JobQueueTest(BaseTest, unittest.TestCase):
     """
 
     def setUp(self):
-        self.jq = JobQueue("Bot", tick_interval=0.005)
+        self.jq = JobQueue("Bot")
         self.result = 0
 
     def tearDown(self):
@@ -61,46 +61,108 @@ class JobQueueTest(BaseTest, unittest.TestCase):
             self.jq.stop()
         stop_con_pool()
 
-    def job1(self, bot):
+    def job1(self, bot, job):
         self.result += 1
 
-    def job2(self, bot):
+    def job2(self, bot, job):
         raise Exception("Test Error")
 
+    def job3(self, bot, job):
+        self.result += 1
+        job.schedule_removal()
+
+    def job4(self, bot, job):
+        self.result += job.context
+
     def test_basic(self):
-        self.jq.put(self.job1, 0.1)
+        self.jq.put(Job(self.job1, 0.1))
         sleep(1.5)
         self.assertGreaterEqual(self.result, 10)
 
+    def test_job_with_context(self):
+        self.jq.put(Job(self.job4, 0.1, context=5))
+        sleep(1.5)
+        self.assertGreaterEqual(self.result, 50)
+
     def test_noRepeat(self):
-        self.jq.put(self.job1, 0.1, repeat=False)
+        self.jq.put(Job(self.job1, 0.1, repeat=False))
         sleep(0.5)
         self.assertEqual(1, self.result)
 
     def test_nextT(self):
-        self.jq.put(self.job1, 0.1, next_t=0.5)
+        self.jq.put(Job(self.job1, 0.1), next_t=0.5)
         sleep(0.45)
         self.assertEqual(0, self.result)
         sleep(0.1)
         self.assertEqual(1, self.result)
 
     def test_multiple(self):
-        self.jq.put(self.job1, 0.1, repeat=False)
-        self.jq.put(self.job1, 0.2, repeat=False)
-        self.jq.put(self.job1, 0.4)
+        self.jq.put(Job(self.job1, 0.1, repeat=False))
+        self.jq.put(Job(self.job1, 0.2, repeat=False))
+        self.jq.put(Job(self.job1, 0.4))
         sleep(1)
         self.assertEqual(4, self.result)
 
-    def test_error(self):
-        self.jq.put(self.job2, 0.1)
-        self.jq.put(self.job1, 0.2)
-        self.jq.start()
-        sleep(0.4)
+    def test_disabled(self):
+        j0 = Job(self.job1, 0.1)
+        j1 = Job(self.job1, 0.2)
+
+        self.jq.put(j0)
+        self.jq.put(Job(self.job1, 0.4))
+        self.jq.put(j1)
+
+        j0.enabled = False
+        j1.enabled = False
+
+        sleep(1)
+        self.assertEqual(2, self.result)
+
+    def test_schedule_removal(self):
+        j0 = Job(self.job1, 0.1)
+        j1 = Job(self.job1, 0.2)
+
+        self.jq.put(j0)
+        self.jq.put(Job(self.job1, 0.4))
+        self.jq.put(j1)
+
+        j0.schedule_removal()
+        j1.schedule_removal()
+
+        sleep(1)
+        self.assertEqual(2, self.result)
+
+    def test_schedule_removal_from_within(self):
+        self.jq.put(Job(self.job1, 0.4))
+        self.jq.put(Job(self.job3, 0.2))
+
+        sleep(1)
+        self.assertEqual(3, self.result)
+
+    def test_longer_first(self):
+        self.jq.put(Job(self.job1, 0.2, repeat=False))
+        self.jq.put(Job(self.job1, 0.1, repeat=False))
+        sleep(0.15)
         self.assertEqual(1, self.result)
 
+    def test_error(self):
+        self.jq.put(Job(self.job2, 0.1))
+        self.jq.put(Job(self.job1, 0.2))
+        self.jq.start()
+        sleep(0.5)
+        self.assertEqual(2, self.result)
+
+    def test_jobs_tuple(self):
+        self.jq.stop()
+        jobs = tuple(Job(self.job1, t) for t in range(5, 25))
+
+        for job in jobs:
+            self.jq.put(job)
+
+        self.assertTupleEqual(jobs, self.jq.jobs())
+
     def test_inUpdater(self):
-        u = Updater(bot="MockBot", job_queue_tick_interval=0.005)
-        u.job_queue.put(self.job1, 0.5)
+        u = Updater(bot="MockBot")
+        u.job_queue.put(Job(self.job1, 0.5))
         sleep(0.75)
         self.assertEqual(1, self.result)
         u.stop()

tests/test_updater.py

@@ -72,6 +72,11 @@ class UpdaterTest(BaseTest, unittest.TestCase):
     WebhookHandler
     """
 
+    updater = None
+    received_message = None
+    message_count = None
+    lock = None
+
     def setUp(self):
         self.updater = None
         self.received_message = None
@@ -123,9 +128,12 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         self.received_message = (groups, groupdict)
         self.message_count += 1
 
-    def additionalArgsTest(self, bot, update, update_queue, args):
+    def additionalArgsTest(self, bot, update, update_queue, job_queue, args):
+        job_queue.put(Job(lambda bot, job: job.schedule_removal(), 0.1))
+
         self.received_message = update
         self.message_count += 1
+
         if args[0] == 'resend':
             update_queue.put('/test5 noresend')
         elif args[0] == 'noresend':
@@ -151,13 +159,13 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         d = self.updater.dispatcher
         from telegram.ext import Filters
         handler = MessageHandler([Filters.text], self.telegramHandlerTest)
-        d.addHandler(handler)
+        d.add_handler(handler)
         self.updater.start_polling(0.01)
         sleep(.1)
         self.assertEqual(self.received_message, 'Test')
 
         # Remove handler
-        d.removeHandler(handler)
+        d.remove_handler(handler)
         self.reset()
 
         self.updater.bot.send_messages = 1
@@ -188,7 +196,7 @@ class UpdaterTest(BaseTest, unittest.TestCase):
 
     def test_addTelegramMessageHandlerMultipleMessages(self):
         self._setup_updater('Multiple', 100)
-        self.updater.dispatcher.addHandler(MessageHandler([], self.telegramHandlerTest))
+        self.updater.dispatcher.add_handler(MessageHandler([], self.telegramHandlerTest))
         self.updater.start_polling(0.0)
         sleep(2)
         self.assertEqual(self.received_message, 'Multiple')
@@ -199,13 +207,13 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         d = self.updater.dispatcher
         regobj = re.compile('Te.*')
         handler = RegexHandler(regobj, self.telegramHandlerTest)
-        self.updater.dispatcher.addHandler(handler)
+        self.updater.dispatcher.add_handler(handler)
         self.updater.start_polling(0.01)
         sleep(.1)
         self.assertEqual(self.received_message, 'Test2')
 
         # Remove handler
-        d.removeHandler(handler)
+        d.remove_handler(handler)
         self.reset()
 
         self.updater.bot.send_messages = 1
@@ -216,13 +224,13 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         self._setup_updater('/test')
         d = self.updater.dispatcher
         handler = CommandHandler('test', self.telegramHandlerTest)
-        self.updater.dispatcher.addHandler(handler)
+        self.updater.dispatcher.add_handler(handler)
         self.updater.start_polling(0.01)
         sleep(.1)
         self.assertEqual(self.received_message, '/test')
 
         # Remove handler
-        d.removeHandler(handler)
+        d.remove_handler(handler)
         self.reset()
 
         self.updater.bot.send_messages = 1
@@ -252,14 +260,14 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         self._setup_updater('', messages=0)
         d = self.updater.dispatcher
         handler = StringRegexHandler('Te.*', self.stringHandlerTest)
-        d.addHandler(handler)
+        d.add_handler(handler)
         queue = self.updater.start_polling(0.01)
         queue.put('Test3')
         sleep(.1)
         self.assertEqual(self.received_message, 'Test3')
 
         # Remove handler
-        d.removeHandler(handler)
+        d.remove_handler(handler)
         self.reset()
 
         queue.put('Test3')
@@ -270,7 +278,7 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         self._setup_updater('', messages=0)
         d = self.updater.dispatcher
         handler = StringCommandHandler('test3', self.stringHandlerTest)
-        d.addHandler(handler)
+        d.add_handler(handler)
 
         queue = self.updater.start_polling(0.01)
         queue.put('/test3')
@@ -278,7 +286,7 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         self.assertEqual(self.received_message, '/test3')
 
         # Remove handler
-        d.removeHandler(handler)
+        d.remove_handler(handler)
         self.reset()
 
         queue.put('/test3')
@@ -288,7 +296,7 @@ class UpdaterTest(BaseTest, unittest.TestCase):
     def test_addRemoveErrorHandler(self):
         self._setup_updater('', messages=0)
         d = self.updater.dispatcher
-        d.addErrorHandler(self.errorHandlerTest)
+        d.add_error_handler(self.errorHandlerTest)
         queue = self.updater.start_polling(0.01)
         error = TelegramError("Unauthorized.")
         queue.put(error)
@@ -296,7 +304,7 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         self.assertEqual(self.received_message, "Unauthorized.")
 
         # Remove handler
-        d.removeErrorHandler(self.errorHandlerTest)
+        d.remove_error_handler(self.errorHandlerTest)
         self.reset()
 
         queue.put(error)
@@ -307,8 +315,8 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         self._setup_updater('', messages=0)
         d = self.updater.dispatcher
         handler = StringRegexHandler('.*', self.errorRaisingHandlerTest)
-        d.addHandler(handler)
-        self.updater.dispatcher.addErrorHandler(self.errorHandlerTest)
+        d.add_handler(handler)
+        self.updater.dispatcher.add_error_handler(self.errorHandlerTest)
         queue = self.updater.start_polling(0.01)
 
         queue.put('Test Error 1')
@@ -319,7 +327,7 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         self._setup_updater('')
         d = self.updater.dispatcher
         handler = MessageHandler([], self.telegramHandlerTest)
-        d.addHandler(handler)
+        d.add_handler(handler)
         self.updater.start_polling(0.01, clean=True)
         sleep(.1)
         self.assertEqual(self.message_count, 0)
@@ -328,7 +336,7 @@ class UpdaterTest(BaseTest, unittest.TestCase):
     def test_errorOnGetUpdates(self):
         self._setup_updater('', raise_error=True)
         d = self.updater.dispatcher
-        d.addErrorHandler(self.errorHandlerTest)
+        d.add_error_handler(self.errorHandlerTest)
         self.updater.start_polling(0.01)
         sleep(.1)
         self.assertEqual(self.received_message, "Test Error 2")
@@ -337,7 +345,7 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         self._setup_updater('', messages=0)
         d = self.updater.dispatcher
         handler = TypeHandler(dict, self.stringHandlerTest)
-        d.addHandler(handler)
+        d.add_handler(handler)
         queue = self.updater.start_polling(0.01)
         payload = {"Test": 42}
         queue.put(payload)
@@ -345,7 +353,7 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         self.assertEqual(self.received_message, payload)
 
         # Remove handler
-        d.removeHandler(handler)
+        d.remove_handler(handler)
         self.reset()
 
         queue.put(payload)
@@ -357,8 +365,8 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         d = self.updater.dispatcher
         handler = InlineQueryHandler(self.telegramInlineHandlerTest)
         handler2 = ChosenInlineResultHandler(self.telegramInlineHandlerTest)
-        d.addHandler(handler)
-        d.addHandler(handler2)
+        d.add_handler(handler)
+        d.add_handler(handler2)
         queue = self.updater.start_polling(0.01)
         update = Update(update_id=0, inline_query="testquery")
         update2 = Update(update_id=0, chosen_inline_result="testresult")
@@ -371,8 +379,8 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         self.assertEqual(self.received_message[1], "testresult")
 
         # Remove handler
-        d.removeHandler(handler)
-        d.removeHandler(handler2)
+        d.remove_handler(handler)
+        d.remove_handler(handler2)
         self.reset()
 
         queue.put(update)
@@ -383,7 +391,7 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         self._setup_updater('', messages=0)
         d = self.updater.dispatcher
         handler = CallbackQueryHandler(self.telegramCallbackHandlerTest)
-        d.addHandler(handler)
+        d.add_handler(handler)
         queue = self.updater.start_polling(0.01)
         update = Update(update_id=0, callback_query="testcallback")
         queue.put(update)
@@ -391,7 +399,7 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         self.assertEqual(self.received_message, "testcallback")
 
         # Remove handler
-        d.removeHandler(handler)
+        d.remove_handler(handler)
         self.reset()
 
         queue.put(update)
@@ -402,7 +410,7 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         self._setup_updater('Test5', messages=2)
         d = self.updater.dispatcher
         handler = MessageHandler([], self.asyncHandlerTest)
-        d.addHandler(handler)
+        d.add_handler(handler)
         self.updater.start_polling(0.01)
         sleep(1.2)
         self.assertEqual(self.received_message, 'Test5')
@@ -413,8 +421,9 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         handler = StringCommandHandler('test5',
                                        self.additionalArgsTest,
                                        pass_update_queue=True,
+                                       pass_job_queue=True,
                                        pass_args=True)
-        self.updater.dispatcher.addHandler(handler)
+        self.updater.dispatcher.add_handler(handler)
 
         queue = self.updater.start_polling(0.01)
         queue.put('/test5 resend')
@@ -429,7 +438,7 @@ class UpdaterTest(BaseTest, unittest.TestCase):
                                      self.regexGroupHandlerTest,
                                      pass_groupdict=True,
                                      pass_groups=True)
-        d.addHandler(handler)
+        d.add_handler(handler)
         queue = self.updater.start_polling(0.01)
         queue.put('This is a test message for regex group matching.')
         sleep(.1)
@@ -440,7 +449,7 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         self._setup_updater('Test6', messages=2)
         d = self.updater.dispatcher
         handler = MessageHandler([], self.asyncAdditionalHandlerTest, pass_update_queue=True)
-        d.addHandler(handler)
+        d.add_handler(handler)
         self.updater.start_polling(0.01)
         sleep(1.2)
         self.assertEqual(self.received_message, 'Test6')
@@ -450,7 +459,7 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         self._setup_updater('', messages=0)
         d = self.updater.dispatcher
         handler = MessageHandler([], self.telegramHandlerTest)
-        d.addHandler(handler)
+        d.add_handler(handler)
 
         ip = '127.0.0.1'
         port = randrange(1024, 49152)  # Select random port for travis
@@ -500,7 +509,7 @@ class UpdaterTest(BaseTest, unittest.TestCase):
         self._setup_updater('', messages=0)
         d = self.updater.dispatcher
         handler = MessageHandler([], self.telegramHandlerTest)
-        d.addHandler(handler)
+        d.add_handler(handler)
 
         ip = '127.0.0.1'
         port = randrange(1024, 49152)  # Select random port for travis