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
-
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 pending/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 thetelegram.ext.Job
instance. It can be used to access itsjob.context
or change it to a repeating job.job_kwargs (
dict
) – Arbitrary keyword arguments. Used as arguments forscheduler.add_job
.context (
object
, optional) – Additional data needed for the callback function. Can be accessed throughjob.context
in the callback. Defaults toNone
.name (
str
, optional) – The name of the new job. Defaults tocallback.__name__
.
- 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), context=None, name=None, job_kwargs=None)¶ Creates a new
Job
that runs on a daily 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 thetelegram.ext.Job
instance. It can be used to access itsjob.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
) isNone
, the default timezone of the bot will be used.days (Tuple[
int
], optional) – Defines on which days of the week the job should run (where0-6
correspond to monday - sunday). Defaults toEVERY_DAY
context (
object
, optional) – Additional data needed for the callback function. Can be accessed throughjob.context
in the callback. Defaults toNone
.name (
str
, optional) – The name of the new job. Defaults tocallback.__name__
.job_kwargs (
dict
, optional) – Arbitrary keyword arguments to pass to thescheduler.add_job()
.
- Returns
The new
Job
instance that has been added to the job queue.- Return type
Note
For a note about DST, please see the documentation of APScheduler.
-
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 thetelegram.ext.Job
instance. It can be used to access itsjob.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
) isNone
, 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 throughjob.context
in the callback. Defaults toNone
.name (
str
, optional) – The name of the new job. Defaults tocallback.__name__
.day_is_strict (
bool
, optional) – IfFalse
and day > month.days, will pick the last day in the month. Defaults toTrue
.job_kwargs (
dict
, optional) – Arbitrary keyword arguments to pass to thescheduler.add_job()
.
- Returns
The new
Job
instance that has been added to the job queue.- Return type
-
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 thetelegram.ext.Job
instance. It can be used to access itsjob.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
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.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 (time.tzinfo
) isNone
, the default timezone of the bot will be used.
context (
object
, optional) – Additional data needed for the callback function. Can be accessed throughjob.context
in the callback. Defaults toNone
.name (
str
, optional) – The name of the new job. Defaults tocallback.__name__
.job_kwargs (
dict
, optional) – Arbitrary keyword arguments to pass to thescheduler.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, context=None, name=None, job_kwargs=None)¶ Creates a new
Job
that runs at specified intervals 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 thetelegram.ext.Job
instance. It can be used to access itsjob.context
or change it to a repeating job.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.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 (time.tzinfo
) isNone
, 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
isdatetime.datetime
ordatetime.time
type andlast.tzinfo
isNone
, 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 throughjob.context
in the callback. Defaults toNone
.name (
str
, optional) – The name of the new job. Defaults tocallback.__name__
.job_kwargs (
dict
, optional) – Arbitrary keyword arguments to pass to thescheduler.add_job()
.
- Returns
The new
Job
instance that has been added to the job queue.- Return type
Note
interval is always respected “as-is”. That means that if DST changes during that interval, the job might not run at the time one would expect. It is always recommended to pin servers to UTC time, then time related behaviour can always be expected.
-
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.
-