telegram.ext.JobQueue

class telegram.ext.JobQueue(bot, prevent_autostart=None)

Bases: object

This class allows you to periodically perform tasks with the bot.

queue

PriorityQueue – The queue that holds the Jobs.

bot

telegram.Bot – Bot that’s send to the handlers.

Parameters:bot (telegram.Bot) – The bot instance that should be passed to the jobs.
Deprecated:
prevent_autostart (bool, optional): Thread does not start during initialisation. Use start method instead.
jobs()

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

put(job, next_t=None)

Queue a new job.

Note

This method is deprecated. Please use: run_once, run_daily or run_repeating instead.

Parameters:
  • job (telegram.ext.Job) – The Job instance representing the new job.
  • next_t (int | float | datetime.timedelta | datetime.datetime | datetime.time, optional) –

    Time in or at which the job should run for the first time. 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.
    • datetime.time will be interpreted as a specific time at which the job should run. This could be either today or, if the time has already passed, tomorrow.
run_daily(callback, time, days=(0, 1, 2, 3, 4, 5, 6), context=None, name=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. It should take bot, job as parameters, where job is the telegram.ext.Job instance. It can be used to access it’s Job.context or change it to a repeating job.
  • time (datetime.time) – Time of day at which the job should run.
  • days (Tuple[int], optional) – Defines on which days of the week the job should run. 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__.
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)

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. It should take bot, job as parameters, where job is the telegram.ext.Job instance. It can be used to access it’s 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.
    • 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.
  • 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_repeating(callback, interval, first=None, context=None, name=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. It should take bot, job as parameters, where job is the telegram.ext.Job instance. It can be used to access it’s 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.
    • 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.

    Defaults to interval

  • 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

start()

Starts the job_queue thread.

stop()

Stops the thread.

tick()

Run all jobs that are due and re-enqueue them with their interval.