telegram.ext.jobqueue module

This module contains the classes JobQueue and Job.

class telegram.ext.jobqueue.Days

Bases: object

EVERY_DAY = (0, 1, 2, 3, 4, 5, 6)
FRI = 4
MON = 0
SAT = 5
SUN = 6
THU = 3
TUE = 1
WED = 2
class telegram.ext.jobqueue.Job(callback, interval=None, repeat=True, context=None, days=(0, 1, 2, 3, 4, 5, 6), name=None, job_queue=None)

Bases: object

This class encapsulates a Job

callback

function – The function that the job executes when it’s due

interval

int, float, datetime.timedelta – The interval in which the job runs

days

tuple[int] – A tuple of int values that determine on which days of the week the job runs

repeat

bool – If the job runs periodically or only once

name

str – The name of this job

job_queue

JobQueue – The JobQueue this job belongs to

enabled

bool – Boolean property that decides if this job is currently active

Parameters:
  • callback (function) – The callback function that should be executed by the Job. It should take two parameters bot and job, where job is the Job instance. It can be used to terminate the job or modify its interval.
  • interval (Optional[int, float, datetime.timedelta]) – The interval in which the job will execute its callback function. int and float will be interpreted as seconds. If you don’t set this value, you must set repeat=False and specify next_t when you put the job into the job queue.
  • repeat (Optional[bool]) – If this job should be periodically execute its callback function (True) or only once (False). Defaults to True
  • context (Optional[object]) – Additional data needed for the callback function. Can be accessed through job.context in the callback. Defaults to None
  • days (Optional[tuple[int]]) – Defines on which days of the week the job should run. Defaults to Days.EVERY_DAY
  • name (Optional[str]) – The name of this job. Defaults to callback.__name__
  • (Optional[class (job_queue) – telegram.ext.JobQueue]): The JobQueue this job belongs to. Only optional for backward compatibility with JobQueue.put().
days
enabled
interval
interval_seconds
job_queue

rtype – JobQueue

removed
repeat
run(bot)

Executes the callback function

schedule_removal()

Schedules this job for removal from the JobQueue. It will be removed without executing its callback function again.

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

Bases: object

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

queue

PriorityQueue

bot

telegram.Bot

Parameters:bot (telegram.Bot) – The bot instance that should be passed to the jobs
Deprecated: 5.2
prevent_autostart (Optional[bool]): 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.

Parameters:
  • job (telegram.ext.Job) – The Job instance representing the new job
  • next_t (Optional[int, float, datetime.timedelta, datetime.datetime, datetime.time]) – 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 (function) – The callback function that should be executed by the new job. It should take two parameters bot and job, where job is the Job instance. It can be used to access it’s context or terminate the job.
  • time (datetime.time) – Time of day at which the job should run.
  • days (Optional[tuple[int]]) – Defines on which days of the week the job should run.
  • to Days.EVERY_DAY (Defaults) –
  • context (Optional[object]) – Additional data needed for the callback function. Can be accessed through job.context in the callback. Defaults to None
  • name (Optional[str]) – 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:

Job

run_once(callback, when, context=None, name=None)

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

Parameters:
  • callback (function) – The callback function that should be executed by the new job. It should take two parameters bot and job, where job is the Job instance. It can be used to access it’s 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 (Optional[object]) – Additional data needed for the callback function. Can be accessed through job.context in the callback. Defaults to None
  • name (Optional[str]) – 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:

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 (function) – The callback function that should be executed by the new job. It should take two parameters bot and job, where job is the Job instance. It can be used to access it’s context, terminate the job or change its interval.
  • 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) –
    • 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 (Optional[object]) – Additional data needed for the callback function. Can be accessed through job.context in the callback. Defaults to None
  • name (Optional[str]) – 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:

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.