From d9d7c3302ba977d1290ad915e1ad01a7053a85c1 Mon Sep 17 00:00:00 2001 From: Paolo Lammens Date: Mon, 10 Jun 2019 10:35:10 +0200 Subject: [PATCH] Update callback parameter specification and explanation to context-based; minor formatting --- Extensions-–-JobQueue.md | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/Extensions-–-JobQueue.md b/Extensions-–-JobQueue.md index ed7a0cb..d2833e3 100644 --- a/Extensions-–-JobQueue.md +++ b/Extensions-–-JobQueue.md @@ -3,6 +3,8 @@ This wiki page has been updated to work with the beta version 12 of the python-t This version has proven to be generally stable enough for most usecases. See [the v12 transistion guide](https://github.com/python-telegram-bot/python-telegram-bot/wiki/Transition-guide-to-Version-12.0) for more info. If you're still using version 11.1.0, please see the [old version of this wiki page](https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions-%E2%80%93-JobQueue/0c79111ed68022f4936c2725f9827eac0a5240a0). +We will henceforth assume you're using the `context`-based system. + ## Introduction The extension class `telegram.ext.JobQueue` allows you to perform tasks with a delay or even periodically, at a set interval. Among many other things, you can use it to send regular updates to your subscribers. @@ -12,32 +14,40 @@ The `JobQueue` class is tightly integrated with other `telegram.ext` classes. Si To use the `JobQueue`, you don't have to do much. When you instantiate the `Updater`, it will create a `JobQueue` for you: ```python +import telegram.ext from telegram.ext import Updater + u = Updater('TOKEN', use_context=True) j = u.job_queue ``` This job queue is also linked to the dispatcher, which is discussed later in this article. Just know that unless you have a good reason to do so, you should not instantiate `JobQueue` yourself. -Tasks in the job queue is encapsulated by the `Job` class. It takes a callback function as a parameter, which will be executed when the time comes. This callback function always takes the two parameters `bot` and `job`. Similar to handler callbacks used by the `Dispatcher`, `bot` is the `telegram.Bot` instance from your `Updater`. `job` is the `Job` instance of that task (more on that later). You can use these 3 methods: `job_queue.run_once()`, `job_queue.run_repeating` and `job_queue.run_daily()` to create jobs with different frequency and time. +Tasks in the job queue are encapsulated by the `Job` class. It takes a callback function as a parameter, which will be executed when the time comes. This callback function always takes one parameter: `context`, a `telegram.ext.CallbackContext`. Like in the case of handler callbacks used by the `Dispatcher`, through this object you can access `context.bot`, the `Updater`'s `telegram.Bot` instance; and for this particular case you can also access `context.job`, which is the `Job` instance of the task that triggered the callback (more on that later). + +You can use the following 3 methods to create jobs with different frequency and time: `job_queue.run_once`, `job_queue.run_repeating` and `job_queue.run_daily`. (As before, you do not usually need to instantiate the `Job` class directly.) + +### Tutorial Add your first job to the queue by defining a callback function and adding it to the job queue. For this tutorial, you can replace `'@examplechannel'` with a channel where your bot is an admin, or by your user id (use [@userinfobot](https://telegram.me/userinfobot) to find out your user id): ```python -def callback_minute(context): +def callback_minute(context: telegram.ext.CallbackContext): context.bot.send_message(chat_id='@examplechannel', text='One message every minute') job_minute = j.run_repeating(callback_minute, interval=60, first=0) ``` +*(Ignore the type annotations if you're on Python 2)* + The `callback_minute` function will be executed every `60.0` seconds, the first time being right now (because of `first=0`). The `interval` and `first` parameters are in seconds if they are `int` or `float`. They can also be `datetime` objects. See the [docs](http://python-telegram-bot.readthedocs.io/en/stable/telegram.ext.jobqueue.html) for detailed explanation. -The return value of these functions are the `Job` objects being created. You can omit `job_minute = ` if you don't need it, I put it here because you can see we can make use of it later in this tutorial. +The return value of these functions are the `Job` objects being created. You don't need to store the result of `run_repeating` (which is the newly instantiated `Job`) if you don't need it; we will make use of it later in this tutorial. You can also add a job that will be executed only once, with a delay: ```python -def callback_30(context): +def callback_30(context: telegram.ext.CallbackContext): context.bot.send_message(chat_id='@examplechannel', text='A single message with 30s delay') @@ -58,7 +68,7 @@ job_minute.schedule_removal() # Remove this job completely A job can also change its own behavior, as it is passed to the callback function as the second argument: ```python -def callback_increasing(context): +def callback_increasing(context: telegram.ext.CallbackContext): job = context.job context.bot.send_message(chat_id='@examplechannel', text='Sending messages with increasing delay up to 10s, then stops.') @@ -75,10 +85,10 @@ You might want to add jobs in response to certain user input, and there is a con ```python from telegram.ext import CommandHandler -def callback_alarm(context): +def callback_alarm(context: telegram.ext.CallbackContext): context.bot.send_message(chat_id=context.job.context, text='BEEP') -def callback_timer(update, context): +def callback_timer(update: telegram.Update, context: telegram.ext.CallbackContext): context.bot.send_message(chat_id=update.message.chat_id, text='Setting a timer for 1 minute!')