README.rst
1Introduction
2============
3
4.. contents::
5
6
7croniter provides iteration for the datetime object with a cron like format.
8
9::
10
11 _ _
12 ___ _ __ ___ _ __ (_) |_ ___ _ __
13 / __| '__/ _ \| '_ \| | __/ _ \ '__|
14 | (__| | | (_) | | | | | || __/ |
15 \___|_| \___/|_| |_|_|\__\___|_|
16
17
18Website: https://github.com/kiorky/croniter
19
20Travis badge
21=============
22.. image:: https://travis-ci.org/kiorky/croniter.png
23 :target: http://travis-ci.org/kiorky/croniter
24
25Usage
26============
27
28A simple example::
29
30 >>> from croniter import croniter
31 >>> from datetime import datetime
32 >>> base = datetime(2010, 1, 25, 4, 46)
33 >>> iter = croniter('*/5 * * * *', base) # every 5 minutes
34 >>> print iter.get_next(datetime) # 2010-01-25 04:50:00
35 >>> print iter.get_next(datetime) # 2010-01-25 04:55:00
36 >>> print iter.get_next(datetime) # 2010-01-25 05:00:00
37 >>>
38 >>> iter = croniter('2 4 * * mon,fri', base) # 04:02 on every Monday and Friday
39 >>> print iter.get_next(datetime) # 2010-01-26 04:02:00
40 >>> print iter.get_next(datetime) # 2010-01-30 04:02:00
41 >>> print iter.get_next(datetime) # 2010-02-02 04:02:00
42 >>>
43 >>> iter = croniter('2 4 1 * wed', base) # 04:02 on every Wednesday OR on 1st day of month
44 >>> print iter.get_next(datetime) # 2010-01-27 04:02:00
45 >>> print iter.get_next(datetime) # 2010-02-01 04:02:00
46 >>> print iter.get_next(datetime) # 2010-02-03 04:02:00
47 >>>
48 >>> iter = croniter('2 4 1 * wed', base, day_or=False) # 04:02 on every 1st day of the month if it is a Wednesday
49 >>> print iter.get_next(datetime) # 2010-09-01 04:02:00
50 >>> print iter.get_next(datetime) # 2010-12-01 04:02:00
51 >>> print iter.get_next(datetime) # 2011-06-01 04:02:00
52 >>> iter = croniter('0 0 * * sat#1,sun#2', base)
53 >>> print iter.get_next(datetime) # datetime.datetime(2010, 2, 6, 0, 0)
54
55All you need to know is how to use the constructor and the ``get_next``
56method, the signature of these methods are listed below::
57
58 >>> def __init__(self, cron_format, start_time=time.time(), day_or=True)
59
60croniter iterates along with ``cron_format`` from ``start_time``.
61``cron_format`` is **min hour day month day_of_week**, you can refer to
62http://en.wikipedia.org/wiki/Cron for more details. The ``day_or``
63switch is used to control how croniter handles **day** and **day_of_week**
64entries. Default option is the cron behaviour, which connects those
65values using **OR**. If the switch is set to False, the values are connected
66using **AND**. This behaves like fcron and enables you to e.g. define a job that
67executes each 2nd friday of a month by setting the days of month and the
68weekday.
69::
70
71 >>> def get_next(self, ret_type=float)
72
73get_next calculates the next value according to the cron expression and
74returns an object of type ``ret_type``. ``ret_type`` should be a ``float`` or a
75``datetime`` object.
76
77Supported added for ``get_prev`` method. (>= 0.2.0)::
78
79 >>> base = datetime(2010, 8, 25)
80 >>> itr = croniter('0 0 1 * *', base)
81 >>> print itr.get_prev(datetime) # 2010-08-01 00:00:00
82 >>> print itr.get_prev(datetime) # 2010-07-01 00:00:00
83 >>> print itr.get_prev(datetime) # 2010-06-01 00:00:00
84
85You can validate your crons using ``is_valid`` class method. (>= 0.3.18)::
86
87 >>> croniter.is_valid('0 0 1 * *') # True
88 >>> croniter.is_valid('0 wrong_value 1 * *') # False
89
90About DST
91=========
92Be sure to init your croniter instance with a TZ aware datetime for this to work !::
93
94 >>> local_date = tz.localize(datetime(2017, 3, 26))
95 >>> val = croniter('0 0 * * *', local_date).get_next(datetime)
96
97Develop this package
98====================
99
100::
101
102 git clone https://github.com/kiorky/croniter.git
103 cd croniter
104 virtualenv --no-site-packages venv
105 . venv/bin/activate
106 pip install --upgrade -r requirements/test.txt
107 py.test src
108
109
110Make a new release
111====================
112We use zest.fullreleaser, a great release infrastructure.
113
114Do and follow these instructions
115::
116
117 . venv/bin/activate
118 pip install --upgrade -r requirements/release.txt
119 fullrelease
120
121
122Contributors
123===============
124Thanks to all who have contributed to this project!
125If you have contributed and your name is not listed below please let me know.
126
127 - mrmachine
128 - Hinnack
129 - shazow
130 - kiorky
131 - jlsandell
132 - mag009
133 - djmitche
134 - GreatCombinator
135 - chris-baynes
136 - ipartola
137 - yuzawa-san
138
139
