The Python APScheduler has three different types of “Triggers”, Interval, Cron and Date. In this tutorial, we will be focusing on the Cron Trigger, and how it can be used to define the scheduling logic for various tasks.
What is the APScheduler Cron Trigger?
Out of all three Triggers in Python APScheduler, Cron is the most widely used and also the most feature rich. What makes the Cron Trigger different from the other two triggers though?
The Cron Trigger is used for “periodically” scheduling tasks. For example, executing a task at a certain time every day, or having a task execute on certain days (like monday to friday).
APScheduler Cron Trigger Parameters
Here’s a look at all the possible parameters for the Python Cron Trigger.
| Name | Datatype | Description |
|---|---|---|
| year | int/str | Value represent a 4 digit year |
| month | int/str | Takes a value from 1 to 12 |
| day | int/str | Takes a value from 1 to 31 |
| week | int/str | ISO Week, values from 1 to 53 |
| day_of_week | int/str | Either 0 to 6, or one from mon, tue, wed, thu, fri, sat, sun. |
| hour | int/str | Takes a value from 0 to 23 |
| minute | int/str | Takes a value from 0 to 59 |
| start_date | datetime/str | The earliest possible date/time to trigger on. |
| end_date | datetime/str | The latest possible date/time to trigger on |
| timezone | datetime.tzinfo/str | Specifies the time zone to use for the date/time calculations |
| jitter | int | Delays the execution of the job by jitter seconds. |
Note, that some of these options take datetime objects are parameters. This is a reference to the Python library datetime, that produces datetime objects.
Expression types for Cron
A list of different expressions that we can create using the Cron Trigger, and an explanation of what they do.
| Expression | Description |
|---|---|
x | Trigger on when x occurs. hour = 3, means trigger on 4th hour. |
| * | Trigger on every value. hour = "*" means every hour. |
| */a | Trigger on every a value. hour = "*/3" means every 3 hours. |
| a-b | Trigger on every value between a and b. hour = '0-11‘ |
| a-b/c | Trigger every c values within the a-b range. |
| xth y (only for days) | Trigger on the x -th occurrence of weekday y within the month |
| last x (only for days) | Triggers on the last x, where x is any day of the week. e.g: last fri. |
| last (only for days) | Triggers on the last day of the month. |
| x,y,z | Used to combine together various expressions using a comma. |
APScheduler Cron Trigger Examples
Now let’s take a look at some actual examples for the cron trigger.
We will go through 7 different examples, each demonstrating a different way in which cron jobs can be scheduled and executed with Python APScheduler.
Example# 1
# Runs every minute at 17 o'clock a day job Method
sched.add_job(job, 'cron', hour= 17, minute= '*',
args= ['job 1'])
The above code uses the special character “*”. This will cause the job to be repeated every minute. If the “*” was placed in the seconds parameter, it would repeat every second.
Example# 2
# Runs every 5 minutes at 17 o'clock a day
sched.add_job(job, 'cron', hour= 17, minute= '*/5',
args= ['job 2'])
The above code is a variation of the first one, but utilizes the */n format. This causes the job to be repeated every “n” number of times.
Example# 3
# Runs once a day at 17:25 and 18:25 job Method
sched.add_job(job, 'cron', hour='17-18', minute= '25',
args= ['job 3'])
This code shows how you can specify a range of values. Hence allowing us to have the code execute over a span of 2 hours, instead of just one.
Example# 4
# Schedules job to be run on the third occurrence of Friday
# on the months June, July, August, November and December
# at 00:00, 01:00, 02:00, 03:00 and 04:00
sched.add_job(job, 'cron', month= '6-8,11-12', day= '3rd fri',
hour= '0-4', args= ['job 4'])
This code demonstrates two new things. First, it shows you can specify multiple ranges, simply by adding commas between them. Secondly, it shows the use of the xth y format, which causes the job to run on the x -th occurrence of weekday y within the month.
There is another option you can make use of, called last. Using last alone causes the code to be run on the last day of the month, otherwise last fri will schedule the job for the last friday of the month.
Example# 5
# Runs from Monday to Friday at 6:30AM until 2022-06-30 00:00:00
sched.add_job(job, 'cron', day_of_week= 'mon-fri', hour= 6,
minute= 30, end_date= '2022-06-30',
args= ['job 5'])
The above code mainly show cases the fact that you can use the end_date option to stop the code from executing once a certain date has been reached.
Example# 6
Here we have a small code snippet that triggers the job every 2 hours, during the interval of the 13th and 24th hour.
sched.add_job(job, 'cron', hour = "12-23/2", args= ['job 7'])
This shows the use of the a-b/c expression type.
Example# 7
This example show cases the use of the jitter option.
When scheduling a large number of tasks to occur at a certain time, this can cause a sudden spike in activity in a split second. To balance these jobs out a bit, and add a random component to them we use the jitter option.
sched.add_job(job, 'cron', hour = '*', jitter = 60)
The above code will execute the job function every hour, but with an extra delay of -60 to +60 seconds.
This marks the end of the Combining Triggers in APScheduler Tutorial. Any suggestions or contributions for CodersLegacy are more than welcome. Questions regarding the tutorial content can be asked in the comments section below.