JobQueue¶
- class telegram.ext.JobQueue[source]¶
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 argumentcontext
of the job callbacks (callback
) ofrun_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
See also
Changed in version 20.0: To use this class, PTB must be installed via
pip install "python-telegram-bot[job-queue]"
.- scheduler[source]¶
The scheduler.
Warning
This scheduler is configured by
set_application()
. Additional configuration settings can be made by users. However, callingconfigure()
will delete any previous configuration settings. Therefore, please make sure to pass the values returned byscheduler_configuration
to the method call in addition to your custom values. Alternatively, you can also use methods likeadd_jobstore()
to avoid usingconfigure()
altogether.Changed in version 20.0: Uses
AsyncIOScheduler
instead ofBackgroundScheduler
- __repr__()[source]¶
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:
- get_jobs_by_name(name)[source]¶
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)[source]¶
This method is used as a callback for the APScheduler jobs.
More precisely, the
func
argument ofapscheduler.job.Job
is set to this method and thearg
argument (representing positional arguments tofunc
) is set to a tuple containing theJobQueue
itself and theJob
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.
- jobs()[source]¶
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)[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 forapscheduler.schedulers.base.BaseScheduler.add_job()
.Additional data needed for the callback function. Can be accessed through
Job.data
in the callback. Defaults toNone
.Changed in version 20.0: Renamed the parameter
context
todata
.name (
str
, optional) – The name of the new job. Defaults tocallback.__name__
.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 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:
- 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
) isNone
, the default timezone of the bot will be used, which is UTC unlesstelegram.ext.Defaults.tzinfo
is used.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.
Additional data needed for the callback function. Can be accessed through
Job.data
in the callback. Defaults toNone
.Changed in version 20.0: Renamed the parameter
context
todata
.name (
str
, optional) – The name of the new job. Defaults tocallback.__name__
.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 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 theapscheduler.schedulers.base.BaseScheduler.add_job()
.
- Returns:
The new
Job
instance that has been added to the job queue.- Return type:
- 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 theday
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
) isNone
, the default timezone of the bot will be used, which is UTC unlesstelegram.ext.Defaults.tzinfo
is used.day (
int
) – Defines the day of the month whereby the job would run. It should be within the range of1
and31
, 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.Additional data needed for the callback function. Can be accessed through
Job.data
in the callback. Defaults toNone
.Changed in version 20.0: Renamed the parameter
context
todata
.name (
str
, optional) – The name of the new job. Defaults tocallback.__name__
.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 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 theapscheduler.schedulers.base.BaseScheduler.add_job()
.
- Returns:
The new
Job
instance that has been added to the job queue.- Return type:
- 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:
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
orfloat
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
) isNone
, the default timezone of the bot will be used, which is UTC unlesstelegram.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
) isNone
, the default timezone of the bot will be used, which is UTC unlesstelegram.ext.Defaults.tzinfo
is used.
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 of the user associated with this job. If passed, the corresponding
user_data
will be available in the callback.Added in version 20.0.
Additional data needed for the callback function. Can be accessed through
Job.data
in the callback. Defaults toNone
.Changed in version 20.0: Renamed the parameter
context
todata
.name (
str
, optional) – The name of the new job. Defaults tocallback.__name__
.job_kwargs (
dict
, optional) – Arbitrary keyword arguments to pass to theapscheduler.schedulers.base.BaseScheduler.add_job()
.
- Returns:
The new
Job
instance that has been added to the job queue.- Return type:
- 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:
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 anint
or afloat
, 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
orfloat
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
) isNone
, 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
) isNone
, the default timezone of the bot will be used, which is UTC unlesstelegram.ext.Defaults.tzinfo
is used.
Defaults to
interval
Note
Setting
first
to0
,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
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
isdatetime.datetime
ordatetime.time
type andlast.tzinfo
isNone
, the default timezone of the bot will be assumed, which is UTC unlesstelegram.ext.Defaults.tzinfo
is used.Defaults to
None
.Additional data needed for the callback function. Can be accessed through
Job.data
in the callback. Defaults toNone
.Changed in version 20.0: Renamed the parameter
context
todata
.name (
str
, optional) – The name of the new job. Defaults tocallback.__name__
.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 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 theapscheduler.schedulers.base.BaseScheduler.add_job()
.
- Returns:
The new
Job
instance that has been added to the job queue.- Return type:
- property scheduler_configuration[source]¶
Provides configuration values that are used by
JobQueue
forscheduler
.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 usingconfigure()
altogether.Added in version 20.7.
- set_application(application)[source]¶
Set the application to be used by this JobQueue.
- Parameters:
application (
telegram.ext.Application
) – The application.