python-telegram-bot · jh0ker · Jun 29, 2016 · May 25, 2016 · May 25, 2016 · May 25, 2016
diff --git a/examples/timerbot.py b/examples/timerbot.py
@@ -17,15 +17,15 @@
 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,46 +34,58 @@ 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 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
         due = int(args[0])
         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 """
+        def alarm(bot, job):
+            """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)
+        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()
+    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
 
     # 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)

diff --git a/telegram/ext/__init__.py b/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
@@ -32,7 +32,7 @@
 from .stringregexhandler import StringRegexHandler
 from .typehandler import TypeHandler
 
-__all__ = ('Dispatcher', 'JobQueue', 'Updater', 'CallbackQueryHandler',
+__all__ = ('Dispatcher', 'JobQueue', 'Job', 'Updater', 'CallbackQueryHandler',
            'ChosenInlineResultHandler', 'CommandHandler', 'Handler', 'InlineQueryHandler',
            'MessageHandler', 'Filters', 'RegexHandler', 'StringCommandHandler',
            'StringRegexHandler', 'TypeHandler')
diff --git a/telegram/ext/callbackqueryhandler.py b/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

diff --git a/telegram/ext/choseninlineresulthandler.py b/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

diff --git a/telegram/ext/commandhandler.py b/telegram/ext/commandhandler.py
@@ -40,18 +40,26 @@ 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,
                  command,
                  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

diff --git a/telegram/ext/dispatcher.py b/telegram/ext/dispatcher.py
@@ -94,11 +94,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]"""

diff --git a/telegram/ext/handler.py b/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):
         """
@@ -77,6 +83,8 @@ def collect_optional_args(self, dispatcher):
         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
 

diff --git a/telegram/ext/inlinequeryhandler.py b/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