| 1 |
:mod:`apscheduler.triggers.cron` |
| 2 |
================================ |
| 3 |
|
| 4 |
.. automodule:: apscheduler.triggers.cron |
| 5 |
|
| 6 |
API |
| 7 |
--- |
| 8 |
|
| 9 |
Trigger alias for :meth:`~apscheduler.schedulers.base.BaseScheduler.add_job`: ``cron`` |
| 10 |
|
| 11 |
.. autoclass:: CronTrigger |
| 12 |
:show-inheritance: |
| 13 |
|
| 14 |
|
| 15 |
Introduction |
| 16 |
------------ |
| 17 |
|
| 18 |
This is the most powerful of the built-in triggers in APScheduler. You can specify a variety of different expressions |
| 19 |
on each field, and when determining the next execution time, it finds the earliest possible time that satisfies the |
| 20 |
conditions in every field. This behavior resembles the "Cron" utility found in most UNIX-like operating systems. |
| 21 |
|
| 22 |
You can also specify the starting date and ending dates for the cron-style schedule through the ``start_date`` and |
| 23 |
``end_date`` parameters, respectively. They can be given as a date/datetime object or text (in the |
| 24 |
`ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ format). |
| 25 |
|
| 26 |
Unlike with crontab expressions, you can omit fields that you don't need. Fields greater than the least significant |
| 27 |
explicitly defined field default to ``*`` while lesser fields default to their minimum values except for ``week`` and |
| 28 |
``day_of_week`` which default to ``*``. For example, ``day=1, minute=20`` is equivalent to |
| 29 |
``year='*', month='*', day=1, week='*', day_of_week='*', hour='*', minute=20, second=0``. The job will then execute |
| 30 |
on the first day of every month on every year at 20 minutes of every hour. The code examples below should further |
| 31 |
illustrate this behavior. |
| 32 |
|
| 33 |
.. note:: The behavior for omitted fields was changed in APScheduler 2.0. |
| 34 |
Omitted fields previously always defaulted to ``*``. |
| 35 |
|
| 36 |
|
| 37 |
Expression types |
| 38 |
---------------- |
| 39 |
|
| 40 |
The following table lists all the available expressions for use in the fields from year to second. |
| 41 |
Multiple expression can be given in a single field, separated by commas. |
| 42 |
|
| 43 |
============== ===== ======================================================================================= |
| 44 |
Expression Field Description |
| 45 |
============== ===== ======================================================================================= |
| 46 |
``*`` any Fire on every value |
| 47 |
``*/a`` any Fire every ``a`` values, starting from the minimum |
| 48 |
``a-b`` any Fire on any value within the ``a-b`` range (a must be smaller than b) |
| 49 |
``a-b/c`` any Fire every ``c`` values within the ``a-b`` range |
| 50 |
``xth y`` day Fire on the ``x`` -th occurrence of weekday ``y`` within the month |
| 51 |
``last x`` day Fire on the last occurrence of weekday ``x`` within the month |
| 52 |
``last`` day Fire on the last day within the month |
| 53 |
``x,y,z`` any Fire on any matching expression; can combine any number of any of the above expressions |
| 54 |
============== ===== ======================================================================================= |
| 55 |
|
| 56 |
.. note:: The ``month`` and ``day_of_week`` fields accept abbreviated English month and weekday names |
| 57 |
(``jan`` – ``dec`` and ``mon`` – ``sun``) respectively. |
| 58 |
|
| 59 |
|
| 60 |
Daylight saving time behavior |
| 61 |
----------------------------- |
| 62 |
|
| 63 |
The cron trigger works with the so-called "wall clock" time. Thus, if the selected time zone observes DST (daylight |
| 64 |
saving time), you should be aware that it may cause unexpected behavior with the cron trigger when entering or leaving |
| 65 |
DST. When switching from standard time to daylight saving time, clocks are moved either one hour or half an hour |
| 66 |
forward, depending on the time zone. Likewise, when switching back to standard time, clocks are moved one hour or half |
| 67 |
an hour backward. This will cause some time periods to either not exist at all, or be repeated. If your schedule would |
| 68 |
have the job executed on either one of these periods, it may execute more often or less often than expected. |
| 69 |
This is not a bug. If you wish to avoid this, either use a timezone that does not observe DST, e.g. UTC, or find out |
| 70 |
about the DST-switch times and avoid using them in your scheduling. |
| 71 |
|
| 72 |
For example, the following schedule may be problematic:: |
| 73 |
|
| 74 |
# In the Europe/Helsinki timezone, this will not execute at all on the last sunday morning of March |
| 75 |
# Likewise, it will execute twice on the last sunday morning of October |
| 76 |
sched.add_job(job_function, 'cron', hour=3, minute=30) |
| 77 |
|
| 78 |
|
| 79 |
Examples |
| 80 |
-------- |
| 81 |
|
| 82 |
:: |
| 83 |
|
| 84 |
from apscheduler.schedulers.blocking import BlockingScheduler |
| 85 |
|
| 86 |
|
| 87 |
def job_function(): |
| 88 |
print "Hello World" |
| 89 |
|
| 90 |
sched = BlockingScheduler() |
| 91 |
|
| 92 |
# Schedules job_function to be run on the third Friday |
| 93 |
# of June, July, August, November and December at 00:00, 01:00, 02:00 and 03:00 |
| 94 |
sched.add_job(job_function, 'cron', month='6-8,11-12', day='3rd fri', hour='0-3') |
| 95 |
|
| 96 |
sched.start() |
| 97 |
|
| 98 |
|
| 99 |
You can use ``start_date`` and ``end_date`` to limit the total time in which the schedule runs:: |
| 100 |
|
| 101 |
# Runs from Monday to Friday at 5:30 (am) until 2014-05-30 00:00:00 |
| 102 |
sched.add_job(job_function, 'cron', day_of_week='mon-fri', hour=5, minute=30, end_date='2014-05-30') |
| 103 |
|
| 104 |
|
| 105 |
The :meth:`~apscheduler.schedulers.base.BaseScheduler.scheduled_job` decorator works nicely too:: |
| 106 |
|
| 107 |
@sched.scheduled_job('cron', id='my_job_id', day='last sun') |
| 108 |
def some_decorated_task(): |
| 109 |
print("I am printed at 00:00:00 on the last Sunday of every month!") |
| 110 |
|
| 111 |
To schedule a job using a standard crontab expression:: |
| 112 |
|
| 113 |
sched.add_job(job_function, CronTrigger.from_crontab('0 0 1-15 may-aug *')) |
| 114 |
|
| 115 |
The ``jitter`` option enables you to add a random component to the execution time. This might be useful if you have |
| 116 |
multiple servers and don't want them to run a job at the exact same moment or if you want to prevent jobs from running |
| 117 |
at sharp hours:: |
| 118 |
|
| 119 |
# Run the `job_function` every sharp hour with an extra-delay picked randomly in a [-120,+120] seconds window. |
| 120 |
sched.add_job(job_function, 'cron', hour='*', jitter=120) |