mirror of
https://github.com/python-telegram-bot/python-telegram-bot.git
synced 2024-11-22 07:06:26 +01:00
Update callback parameter specification and explanation to context-based; minor formatting
parent
c83f785116
commit
d9d7c3302b
1 changed files with 17 additions and 7 deletions
|
@ -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!')
|
||||
|
||||
|
|
Loading…
Reference in a new issue