telegram.ext.JobQueue

class telegram.ext.JobQueue

Bases: object

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

scheduler

The APScheduler

Type

apscheduler.schedulers.background.BackgroundScheduler

bot

The bot instance that should be passed to the jobs. DEPRECATED: Use set_dispatcher instead.

Type

telegram.Bot

get_jobs_by_name(name)

Returns a tuple of all pending/scheduled jobs with the given name that are currently in the JobQueue.

jobs()

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

run_custom(callback, job_kwargs, context=None, name=None)

Creates a new customly defined Job.

Parameters
  • callback (callable) –

    The callback function that should be executed by the new job. Callback signature for context based API:

    def callback(CallbackContext)

    context.job is the telegram.ext.Job instance. It can be used to access its job.context or change it to a repeating job.

  • job_kwargs (dict) – Arbitrary keyword arguments. Used as arguments for scheduler.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__.

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, 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 (callable) –

    The callback function that should be executed by the new job. Callback signature for context based API:

    def callback(CallbackContext)

    context.job is the telegram.ext.Job instance. It can be used to access its job.context or change it to a repeating job.

  • time (datetime.time) – Time of day at which the job should run. If the timezone (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__.

  • job_kwargs (dict, optional) – Arbitrary keyword arguments to pass to the scheduler.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, day_is_strict=True, job_kwargs=None)

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

Parameters
  • callback (callable) –

    The callback function that should be executed by the new job. Callback signature for context based API:

    def callback(CallbackContext)

    context.job is the telegram.ext.Job instance. It can be used to access its job.context or change it to a repeating job.

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

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

  • day_is_strict (bool, optional) – If False and day > month.days, will pick the last day in the month. Defaults to True.

  • job_kwargs (dict, optional) – Arbitrary keyword arguments to pass to the scheduler.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, job_kwargs=None)

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

Parameters
  • callback (callable) –

    The callback function that should be executed by the new job. Callback signature for context based API:

    def callback(CallbackContext)

    context.job is the telegram.ext.Job instance. It can be used to access its job.context or change it to a repeating job.

  • 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.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 (time.tzinfo) is None, the default timezone of the bot will be used.

  • 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 scheduler.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, job_kwargs=None)

Creates a new Job 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 (callable) –

    The callback function that should be executed by the new job. Callback signature for context based API:

    def callback(CallbackContext)

    context.job is the telegram.ext.Job instance. It can be used to access its job.context or change it to a repeating job.

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

  • job_kwargs (dict, optional) – Arbitrary keyword arguments to pass to the scheduler.add_job().

Returns

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

Return type

telegram.ext.Job

set_dispatcher(dispatcher)

Set the dispatcher to be used by this JobQueue. Use this instead of passing a telegram.Bot to the JobQueue, which is deprecated.

Parameters

dispatcher (telegram.ext.Dispatcher) – The dispatcher.

start()

Starts the job_queue thread.

stop()

Stops the thread.