telegram.ext.JobQueue#

class telegram.ext.JobQueue[source]#

Bases: object

This class allows you to periodically perform tasks with the bot. It is a convenience wrapper for the APScheduler library.

scheduler[source]#

The scheduler.

Changed in version 20.0: Use AsyncIOScheduler instead of BackgroundScheduler

Type: apscheduler.schedulers.asyncio.AsyncIOScheduler

property application[source]#: The application this JobQueue is associated with.

get_jobs_by_name(name)[source]#: Returns a tuple of all pending/scheduled jobs with the given name that are currently in the JobQueue.

jobs()[source]#: Returns a tuple of all scheduled jobs that are currently in the JobQueue.

run_custom(callback, job_kwargs, context=None, name=None, chat_id=None, user_id=None)[source]#

Creates a new custom defined Job.

Parameters

callback (coroutine function) –
The callback function that should be executed by the new job. Callback signature:
```
async def callback(context: CallbackContext)
```
job_kwargs (dict) – Arbitrary keyword arguments. Used as arguments for apscheduler.schedulers.base.BaseScheduler.add_job().
context (object, optional) – Additional data needed for the callback function. Can be accessed through Job.context in the callback. Defaults to None.
name (str, optional) – The name of the new job. Defaults to callback.__name__.
chat_id (int, optional) –
Chat id of the chat associated with this job. If passed, the corresponding chat_data will be available in the callback.

New in version 20.0.
user_id (int, optional) –
User id of the user associated with this job. If passed, the corresponding user_data will be available in the callback.

New in version 20.0.

Returns

The new Job instance that has been added to the job queue.

Return type

telegram.ext.Job

run_daily(callback, time, days=(0, 1, 2, 3, 4, 5, 6), context=None, name=None, chat_id=None, user_id=None, job_kwargs=None)[source]#

Creates a new Job that runs on a daily basis and adds it to the queue.

Note

For a note about DST, please see the documentation of APScheduler.

Parameters

callback (coroutine function) –
The callback function that should be executed by the new job. Callback signature:
```
async def callback(context: CallbackContext)
```
time (datetime.time) – Time of day at which the job should run. If the timezone (datetime.time.tzinfo) is None, the default timezone of the bot will be used.
days (Tuple[int], optional) – Defines on which days of the week the job should run (where 0-6 correspond to monday - sunday). Defaults to EVERY_DAY
context (object, optional) – Additional data needed for the callback function. Can be accessed through Job.context in the callback. Defaults to None.
name (str, optional) – The name of the new job. Defaults to callback.__name__.
chat_id (int, optional) –
Chat id of the chat associated with this job. If passed, the corresponding chat_data will be available in the callback.

New in version 20.0.
user_id (int, optional) –
User id of the user associated with this job. If passed, the corresponding user_data will be available in the callback.

New in version 20.0.
job_kwargs (dict, optional) – Arbitrary keyword arguments to pass to the apscheduler.schedulers.base.BaseScheduler.add_job().

Returns

The new Job instance that has been added to the job queue.

Return type

telegram.ext.Job

run_monthly(callback, when, day, context=None, name=None, chat_id=None, user_id=None, job_kwargs=None)[source]#

Creates a new Job that runs on a monthly basis and adds it to the queue.

Changed in version 20.0: The day_is_strict argument was removed. Instead one can now pass -1 to the day parameter to have the job run on the last day of the month.

Parameters

callback (coroutine function) –
The callback function that should be executed by the new job. Callback signature:
```
async def callback(context: CallbackContext)
```
when (datetime.time) – Time of day at which the job should run. If the timezone (when.tzinfo) is None, the default timezone of the bot will be used.
day (int) – Defines the day of the month whereby the job would run. It should be within the range of 1 and 31, inclusive. If a month has fewer days than this number, the job will not run in this month. Passing -1 leads to the job running on the last day of the month.
context (object, optional) – Additional data needed for the callback function. Can be accessed through Job.context in the callback. Defaults to None.
name (str, optional) – The name of the new job. Defaults to callback.__name__.
chat_id (int, optional) –
Chat id of the chat associated with this job. If passed, the corresponding chat_data will be available in the callback.

New in version 20.0.
user_id (int, optional) –
User id of the user associated with this job. If passed, the corresponding user_data will be available in the callback.

New in version 20.0.
job_kwargs (dict, optional) – Arbitrary keyword arguments to pass to the apscheduler.schedulers.base.BaseScheduler.add_job().

Returns

The new Job instance that has been added to the job queue.

Return type

telegram.ext.Job

run_once(callback, when, context=None, name=None, chat_id=None, user_id=None, job_kwargs=None)[source]#

Creates a new Job instance that runs once and adds it to the queue.

Parameters

callback (coroutine function) –
The callback function that should be executed by the new job. Callback signature:
```
async def callback(context: CallbackContext)
```
when (int | float | datetime.timedelta | datetime.datetime | datetime.time) –
Time in or at which the job should run. This parameter will be interpreted depending on its type.
- int or float will be interpreted as “seconds from now” in which the job should run.
- datetime.timedelta will be interpreted as “time from now” in which the job should run.
- datetime.datetime will be interpreted as a specific date and time at which the job should run. If the timezone (datetime.datetime.tzinfo) is None, the default timezone of the bot will be used.
- datetime.time will be interpreted as a specific time of day at which the job should run. This could be either today or, if the time has already passed, tomorrow. If the timezone (datetime.time.tzinfo) is None, the default timezone of the bot will be used.
chat_id (int, optional) –
Chat id of the chat associated with this job. If passed, the corresponding chat_data will be available in the callback.

New in version 20.0.
user_id (int, optional) –
User id of the user associated with this job. If passed, the corresponding user_data will be available in the callback.

New in version 20.0.
context (object, optional) – Additional data needed for the callback function. Can be accessed through Job.context in the callback. Defaults to None.
name (str, optional) – The name of the new job. Defaults to callback.__name__.
job_kwargs (dict, optional) – Arbitrary keyword arguments to pass to the apscheduler.schedulers.base.BaseScheduler.add_job().

Returns

The new Job instance that has been added to the job queue.

Return type

telegram.ext.Job

run_repeating(callback, interval, first=None, last=None, context=None, name=None, chat_id=None, user_id=None, job_kwargs=None)[source]#

Creates a new Job instance that runs at specified intervals and adds it to the queue.

Note

For a note about DST, please see the documentation of APScheduler.

Parameters

callback (coroutine function) –
The callback function that should be executed by the new job. Callback signature:
```
async def callback(context: CallbackContext)
```
interval (int | float | datetime.timedelta) – The interval in which the job will run. If it is an int or a float, it will be interpreted as seconds.
first (int | float | datetime.timedelta | datetime.datetime | datetime.time, optional) –
Time in or at which the job should run. This parameter will be interpreted depending on its type.
- int or float will be interpreted as “seconds from now” in which the job should run.
- datetime.timedelta will be interpreted as “time from now” in which the job should run.
- datetime.datetime will be interpreted as a specific date and time at which the job should run. If the timezone (datetime.datetime.tzinfo) is None, the default timezone of the bot will be used.
- datetime.time will be interpreted as a specific time of day at which the job should run. This could be either today or, if the time has already passed, tomorrow. If the timezone (datetime.time.tzinfo) is None, the default timezone of the bot will be used.
Defaults to interval
last (int | float | datetime.timedelta | datetime.datetime | datetime.time, optional) –
Latest possible time for the job to run. This parameter will be interpreted depending on its type. See first for details.

If last is datetime.datetime or datetime.time type and last.tzinfo is None, the default timezone of the bot will be assumed.

Defaults to None.
context (object, optional) – Additional data needed for the callback function. Can be accessed through Job.context in the callback. Defaults to None.
name (str, optional) – The name of the new job. Defaults to callback.__name__.
chat_id (int, optional) –
Chat id of the chat associated with this job. If passed, the corresponding chat_data will be available in the callback.

New in version 20.0.
user_id (int, optional) –
User id of the user associated with this job. If passed, the corresponding user_data will be available in the callback.

New in version 20.0.
job_kwargs (dict, optional) – Arbitrary keyword arguments to pass to the apscheduler.schedulers.base.BaseScheduler.add_job().

Returns

The new Job instance that has been added to the job queue.

Return type

telegram.ext.Job

set_application(application)[source]#

Set the application to be used by this JobQueue.

Parameters: application (telegram.ext.Application) – The application.

async start()[source]#: Starts the job_queue.

async stop(wait=True)[source]#

Shuts down the JobQueue.

Parameters: wait (bool, optional) – Whether to wait until all currently running jobs have finished. Defaults to True.