croniter 3.0.3

简介

croniter提供了类似于cron格式的datetime对象的迭代。

                      _ _
  ___ _ __ ___  _ __ (_) |_ ___ _ __
 / __| '__/ _ \| '_ \| | __/ _ \ '__|
| (__| | | (_) | | | | | ||  __/ |
 \___|_|  \___/|_| |_|_|\__\___|_|

网站：https://github.com/kiorky/croniter

构建徽章

用法

简单示例

>>> from croniter import croniter
>>> from datetime import datetime
>>> base = datetime(2010, 1, 25, 4, 46)
>>> iter = croniter('*/5 * * * *', base)  # every 5 minutes
>>> print(iter.get_next(datetime))   # 2010-01-25 04:50:00
>>> print(iter.get_next(datetime))   # 2010-01-25 04:55:00
>>> print(iter.get_next(datetime))   # 2010-01-25 05:00:00
>>>
>>> iter = croniter('2 4 * * mon,fri', base)  # 04:02 on every Monday and Friday
>>> print(iter.get_next(datetime))   # 2010-01-26 04:02:00
>>> print(iter.get_next(datetime))   # 2010-01-30 04:02:00
>>> print(iter.get_next(datetime))   # 2010-02-02 04:02:00
>>>
>>> iter = croniter('2 4 1 * wed', base)  # 04:02 on every Wednesday OR on 1st day of month
>>> print(iter.get_next(datetime))   # 2010-01-27 04:02:00
>>> print(iter.get_next(datetime))   # 2010-02-01 04:02:00
>>> print(iter.get_next(datetime))   # 2010-02-03 04:02:00
>>>
>>> iter = croniter('2 4 1 * wed', base, day_or=False)  # 04:02 on every 1st day of the month if it is a Wednesday
>>> print(iter.get_next(datetime))   # 2010-09-01 04:02:00
>>> print(iter.get_next(datetime))   # 2010-12-01 04:02:00
>>> print(iter.get_next(datetime))   # 2011-06-01 04:02:00
>>>
>>> iter = croniter('0 0 * * sat#1,sun#2', base)  # 1st Saturday, and 2nd Sunday of the month
>>> print(iter.get_next(datetime))   # 2010-02-06 00:00:00
>>>
>>> iter = croniter('0 0 * * 5#3,L5', base)  # 3rd and last Friday of the month
>>> print(iter.get_next(datetime))   # 2010-01-29 00:00:00
>>> print(iter.get_next(datetime))   # 2010-02-19 00:00:00

您需要了解的只是如何使用构造函数和get_next方法，这些方法的签名如下

>>> def __init__(self, cron_format, start_time=time.time(), day_or=True)

croniter从start_time开始，按照cron_format迭代。 cron_format的格式为min hour day month day_of_week，更多详情请参考http://zh.wikipedia.org/wiki/Cron。 day_or开关用于控制croniter如何处理day和day_of_week条目。默认选项是cron的行为，使用OR连接这些值。如果开关设置为False，则使用AND连接这些值。这类似于fcron，并允许您例如通过设置月份和星期几来定义每个月第二个星期五执行的任务。

>>> def get_next(self, ret_type=float)

get_next根据cron表达式计算下一个值，并返回类型为ret_type的对象。 ret_type应该是一个浮点数或一个datetime对象。

支持为get_prev方法添加。(>= 0.2.0)

>>> base = datetime(2010, 8, 25)
>>> itr = croniter('0 0 1 * *', base)
>>> print(itr.get_prev(datetime))  # 2010-08-01 00:00:00
>>> print(itr.get_prev(datetime))  # 2010-07-01 00:00:00
>>> print(itr.get_prev(datetime))  # 2010-06-01 00:00:00

您可以使用is_valid类方法验证您的cron。(>= 0.3.18)

>>> croniter.is_valid('0 0 1 * *')  # True
>>> croniter.is_valid('0 wrong_value 1 * *')  # False

关于DST

请确保使用带时区的datetime初始化croniter实例，以便此功能生效！

使用pytz的示例

>>> import pytz
>>> tz = pytz.timezone("Europe/Paris")
>>> local_date = tz.localize(datetime(2017, 3, 26))
>>> val = croniter('0 0 * * *', local_date).get_next(datetime)

使用python_dateutil的示例

>>> import dateutil.tz
>>> tz = dateutil.tz.gettz('Asia/Tokyo')
>>> local_date = datetime(2017, 3, 26, tzinfo=tz)
>>> val = croniter('0 0 * * *', local_date).get_next(datetime)

使用python内置模块的示例

>>> from datetime import datetime, timezone
>>> local_date = datetime(2017, 3, 26, tzinfo=timezone.utc)
>>> val = croniter('0 0 * * *', local_date).get_next(datetime)

关于秒重复

Croniter能够处理带有秒重复的crontab格式，默认情况下，秒是第6个字段

>>> base = datetime(2012, 4, 6, 13, 26, 10)
>>> itr = croniter('* * * * * 15,25', base)
>>> itr.get_next(datetime) # 4/6 13:26:15
>>> itr.get_next(datetime) # 4/6 13:26:25
>>> itr.get_next(datetime) # 4/6 13:27:15

您也可以注意到，此表达式将从开始日期时间起每秒重复一次。

>>> croniter('* * * * * *', local_date).get_next(datetime)

您也可以将秒作为第一个字段使用

>>> itr = croniter('15,25 * * * * *', base, second_at_beginning=True)

关于年

Croniter还支持年份字段。年份位于第7个字段，位于秒重复之后。年份字段的范围是1970年至2099年。要忽略秒重复，只需将秒设置为0或任何其他常量即可

>>> base = datetime(2012, 4, 6, 2, 6, 59)
>>> itr = croniter('0 0 1 1 * 0 2020/2', base)
>>> itr.get_next(datetime) # 2020 1/1 0:0:0
>>> itr.get_next(datetime) # 2022 1/1 0:0:0
>>> itr.get_next(datetime) # 2024 1/1 0:0:0

支持开始时间偏移

请参阅https://github.com/kiorky/croniter/pull/76，您可以将start_time=，然后设置expand_from_start_time=True，以便您的生成从start_time而不是日历天计算

>>> from pprint import pprint
>>> iter = croniter('0 0 */7 * *', start_time=datetime(2024, 7, 11), expand_from_start_time=True);pprint([iter.get_next(datetime) for a in range(10)])
[datetime.datetime(2024, 7, 18, 0, 0),
 datetime.datetime(2024, 7, 25, 0, 0),
 datetime.datetime(2024, 8, 4, 0, 0),
 datetime.datetime(2024, 8, 11, 0, 0),
 datetime.datetime(2024, 8, 18, 0, 0),
 datetime.datetime(2024, 8, 25, 0, 0),
 datetime.datetime(2024, 9, 4, 0, 0),
 datetime.datetime(2024, 9, 11, 0, 0),
 datetime.datetime(2024, 9, 18, 0, 0),
 datetime.datetime(2024, 9, 25, 0, 0)]
>>> # INSTEAD OF THE DEFAULT BEHAVIOR:
>>> iter = croniter('0 0 */7 * *', start_time=datetime(2024, 7, 11), expand_from_start_time=False);pprint([iter.get_next(datetime) for a in range(10)])
[datetime.datetime(2024, 7, 15, 0, 0),
 datetime.datetime(2024, 7, 22, 0, 0),
 datetime.datetime(2024, 7, 29, 0, 0),
 datetime.datetime(2024, 8, 1, 0, 0),
 datetime.datetime(2024, 8, 8, 0, 0),
 datetime.datetime(2024, 8, 15, 0, 0),
 datetime.datetime(2024, 8, 22, 0, 0),
 datetime.datetime(2024, 8, 29, 0, 0),
 datetime.datetime(2024, 9, 1, 0, 0),
 datetime.datetime(2024, 9, 8, 0, 0)]

测试日期是否与crontab匹配

进行匹配测试(>=0.3.32)

>>> croniter.match("0 0 * * *", datetime(2019, 1, 14, 0, 0, 0, 0))
True
>>> croniter.match("0 0 * * *", datetime(2019, 1, 14, 0, 2, 0, 0))
False
>>>
>>> croniter.match("2 4 1 * wed", datetime(2019, 1, 1, 4, 2, 0, 0)) # 04:02 on every Wednesday OR on 1st day of month
True
>>> croniter.match("2 4 1 * wed", datetime(2019, 1, 1, 4, 2, 0, 0), day_or=False) # 04:02 on every 1st day of the month if it is a Wednesday
False

测试crontab是否在datetime范围内匹配

进行匹配范围测试(>=2.0.3)

>>> croniter.match_range("0 0 * * *", datetime(2019, 1, 13, 0, 59, 0, 0), datetime(2019, 1, 14, 0, 1, 0, 0))
True
>>> croniter.match_range("0 0 * * *", datetime(2019, 1, 13, 0, 1, 0, 0), datetime(2019, 1, 13, 0, 59, 0, 0))
False
>>> croniter.match_range("2 4 1 * wed", datetime(2019, 1, 1, 3, 2, 0, 0), datetime(2019, 1, 1, 5, 1, 0, 0))
# 04:02 on every Wednesday OR on 1st day of month
True
>>> croniter.match_range("2 4 1 * wed", datetime(2019, 1, 1, 3, 2, 0, 0), datetime(2019, 1, 1, 5, 2, 0, 0), day_or=False)
# 04:02 on every 1st day of the month if it is a Wednesday
False

日期匹配之间的差距

出于性能原因，croniter限制了尝试查找下一个匹配项所花费的CPU周期数。从v0.3.35开始，此行为可以通过max_years_between_matches参数进行配置，默认窗口已从1年增加到50年。

对于许多用例，默认值应该足够好。评估多个cron表达式或处理来自不受信任来源或最终用户的cron表达式的应用程序应使用此参数。遍历稀疏cron表达式可能会导致CPU消耗增加或引发CroniterBadDateError异常，该异常指示croniter已放弃尝试查找下一个（或上一个）匹配项。显式指定max_years_between_matches提供了一种限制CPU利用率的途径，并通过消除对CroniterBadDateError的需要来简化可迭代接口。可迭代接口的差异基于以下推理：每当显式同意max_years_between_matches时，croniter就没有必要发出已放弃的信号；停止迭代更为可取。

此示例匹配1月1日星期五的凌晨4点。由于1月1日不常是星期五，因此两次发生之间可能有几年。将限制设置为15年可确保所有匹配项

>>> it = croniter("0 4 1 1 fri", datetime(2000,1,1), day_or=False, max_years_between_matches=15).all_next(datetime)
>>> for i in range(5):
...     print(next(it))
...
2010-01-01 04:00:00
2016-01-01 04:00:00
2021-01-01 04:00:00
2027-01-01 04:00:00
2038-01-01 04:00:00

但是，当只关注未来5年内的日期时，只需在上面的示例中将max_years_between_matches=5。这将导致找不到匹配项，但不会浪费在未来的不想要的匹配项上的额外周期。

使用cron迭代范围

使用croniter_range()函数在范围内查找匹配项。这与内置的range(start,stop,step)函数类似，但对于日期。step参数是一个cron表达式。在(>=0.3.34)中添加

列出2019年每个月的第一个星期六

>>> from croniter import croniter_range
>>> for dt in croniter_range(datetime(2019, 1, 1), datetime(2019, 12, 31), "0 0 * * sat#1"):
>>>     print(dt)

哈希表达式

croniter 支持Jenkins风格的哈希表达式，使用“H”定义关键字和所需的hash_id关键字参数。相同的hash_id保证了哈希表达式的稳定性，但不同的hash_id将完全不同。这允许，例如，在不手动分散的情况下，对具有不同名称的作业进行均匀分布。

>>> itr = croniter("H H * * *", hash_id="hello")
>>> itr.get_next(datetime)
datetime.datetime(2021, 4, 10, 11, 10)
>>> itr.get_next(datetime)
datetime.datetime(2021, 4, 11, 11, 10)
>>> itr = croniter("H H * * *", hash_id="hello")
>>> itr.get_next(datetime)
datetime.datetime(2021, 4, 10, 11, 10)
>>> itr = croniter("H H * * *", hash_id="bonjour")
>>> itr.get_next(datetime)
datetime.datetime(2021, 4, 10, 20, 52)

随机表达式

支持随机的“R”定义关键字，并且只在其croniter()实例内保持一致性。

>>> itr = croniter("R R * * *")
>>> itr.get_next(datetime)
datetime.datetime(2021, 4, 10, 22, 56)
>>> itr.get_next(datetime)
datetime.datetime(2021, 4, 11, 22, 56)
>>> itr = croniter("R R * * *")
>>> itr.get_next(datetime)
datetime.datetime(2021, 4, 11, 4, 19)

关键字表达式

支持Vixie cron风格的“@”关键字表达式。它们评估的结果取决于是否提供hash_id：没有hash_id对应于Vixie cron定义（精确时间，分钟分辨率），而有hash_id对应于Jenkins定义（在周期内哈希，秒分辨率）。

关键字	无hash_id	有hash_id
@midnight	0 0 * * *	H H(0-2) * * * H
@hourly	0 * * * *	H * * * * H
@daily	0 0 * * *	H H * * * H
@weekly	0 0 * * 0	H H * * H H
@monthly	0 0 1 * *	H H H * * H
@yearly	0 0 1 1 *	H H H H * H
@annually	0 0 1 1 *	H H H H * H

升级

至2.0.0版本

• 如果您已安装，请使用指定版本的要求/base.txt安装或升级pytz <=2021.1。

开发此包

git clone https://github.com/kiorky/croniter.git
cd croniter
virtualenv --no-site-packages venv
. venv/bin/activate
pip install --upgrade -r requirements/test.txt
py.test src

发布新版本

我们使用 zest.fullreleaser，这是一个出色的发布基础设施。

执行并遵循这些说明

. venv/bin/activate
pip install --upgrade -r requirements/release.txt
./release.sh

贡献者

感谢所有为这个项目做出贡献的人！如果您已经做出贡献，但您的名字下没有列出，请告诉我。

• mrmachine

• Hinnack

• shazow

• kiorky

• jlsandell

• mag009

• djmitche

• GreatCombinator

• chris-baynes

• ipartola

• yuzawa-san

• lowell80 (Kintyre)

• scop

• zed2015

• Ryan Finnie (rfinnie)

• salitaba

变更日志