Debian Codegraph @

docs/modules/triggers/cron.rst

raw
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)