JobQueue

class telegram.ext.JobQueue[source]

Bases: typing.Generic

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

This class is a Generic class and accepts one type variable that specifies the type of the argument context of the job callbacks (callback) of run_once() and the other scheduling methods.

Important

If you want to use this class, you must install PTB with the optional requirement job-queue, i.e.

pip install python-telegram-bot[job-queue]

Examples

Timer Bot

Changed in version 20.0: To use this class, PTB must be installed via pip install python-telegram-bot[job-queue].

scheduler[source]

The scheduler.

Changed in version 20.0: Uses 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.

Returns:

Tuple of all pending or scheduled jobs matching the name.

Return type:

Tuple[Job]

jobs()[source]

Returns a tuple of all scheduled jobs that are currently in the JobQueue.

Returns:

Tuple of all scheduled jobs.

Return type:

Tuple[Job]

run_custom(callback, job_kwargs, data=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().

  • data (object, optional) –

    Additional data needed for the callback function. Can be accessed through Job.data in the callback. Defaults to None.

    Changed in version 20.0: Renamed the parameter context to data.

  • 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), data=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, which is UTC unless telegram.ext.Defaults.tzinfo is used.

  • days (Tuple[int], optional) –

    Defines on which days of the week the job should run (where 0-6 correspond to sunday - saturday). By default, the job will run every day.

    Changed in version 20.0: Changed day of the week mapping of 0-6 from monday-sunday to sunday-saturday.

  • data (object, optional) –

    Additional data needed for the callback function. Can be accessed through Job.data in the callback. Defaults to None.

    Changed in version 20.0: Renamed the parameter context to data.

  • 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, data=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, which is UTC unless telegram.ext.Defaults.tzinfo is 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.

  • data (object, optional) –

    Additional data needed for the callback function. Can be accessed through Job.data in the callback. Defaults to None.

    Changed in version 20.0: Renamed the parameter context to data.

  • 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, data=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:
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, data=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:
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 JobQueue.

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.