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: 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.

jobs()[source]

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

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.

  • 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.

  • 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.