JobQueue

class telegram.ext.JobQueue

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

Use In

telegram.ext.ApplicationBuilder.job_queue()

Available In

• telegram.ext.Application.job_queue

• telegram.ext.CallbackContext.job_queue

See also

Architecture Overview, Job Queue

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

scheduler

The scheduler.

Warning

This scheduler is configured by set_application(). Additional configuration settings can be made by users. However, calling configure() will delete any previous configuration settings. Therefore, please make sure to pass the values returned by scheduler_configuration to the method call in addition to your custom values. Alternatively, you can also use methods like add_jobstore() to avoid using configure() altogether.

Changed in version 20.0: Uses AsyncIOScheduler instead of BackgroundScheduler

Type:

apscheduler.schedulers.asyncio.AsyncIOScheduler

__repr__()

Give a string representation of the JobQueue in the form JobQueue[application=...].

As this class doesn’t implement object.__str__(), the default implementation will be used, which is equivalent to __repr__().

Returns:

str

property application

The application this JobQueue is associated with.

get_jobs_by_name(name)

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]

async static job_callback(job_queue, job)

This method is used as a callback for the APScheduler jobs.

More precisely, the func argument of apscheduler.job.Job is set to this method and the arg argument (representing positional arguments to func) is set to a tuple containing the JobQueue itself and the Job instance.

Tip

This method is a static method rather than a bound method. This makes the arguments more transparent and allows for easier handling of PTBs integration of APScheduler when utilizing advanced features of APScheduler.

Hint

This method is effectively a wrapper for telegram.ext.Job.run().

Added in version 20.4.

Parameters:

• job_queue (JobQueue) – The job queue that created the job.

• job (Job) – The job to run.

jobs()

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)

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.

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

  Added 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)

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.

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

  Added 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)

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.

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

  Added 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)

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

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

  Added in version 20.0.

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

• 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, data=None, name=None, chat_id=None, user_id=None, job_kwargs=None)

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

  Defaults to interval

  Note

  Setting first to 0, datetime.datetime.now() or another value that indicates that the job should run immediately will not work due to how the APScheduler library works. If you want to run a job immediately, we recommend to use an approach along the lines of:

  job = context.job_queue.run_repeating(callback, interval=5)
  await job.run(context.application)
  

  See also

  telegram.ext.Job.run()

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

  Defaults to None.

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

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

  Added 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

property scheduler_configuration

Provides configuration values that are used by JobQueue for scheduler.

Tip

Since calling scheduler.configure() deletes any previous setting, please make sure to pass these values to the method call in addition to your custom values:

scheduler.configure(..., **job_queue.scheduler_configuration)

Alternatively, you can also use methods like add_jobstore() to avoid using configure() altogether.

Added in version 20.7.

Returns:

The configuration values as dictionary.

Return type:

Dict[str, object]

set_application(application)

Set the application to be used by this JobQueue.

Parameters:

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

async start()

Starts the JobQueue.

async stop(wait=True)

Shuts down the JobQueue.

Parameters:

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