mirror of
https://github.com/ThearchyHelios/AgentLab.git
synced 2026-11-16 23:12:00 +00:00
定时任务 cron:自写五字段解析、下次 / 上次触发和中文描述,不加依赖
- 分 时 日 月 周五个字段,支持 *、列表、范围、步长和月份 / 星期的英文缩写,周日写 0 或 7;日、周都受限时取 「或」,有一边以 * 开头就只看另一边(和 Linux 系统的 cron 一致,同一个表达式在这里和服务器上意思相同) - 按任务时区的墙上时间匹配:夏令时跳过的本地时间那天不触发,拨回时重复的本地时间只在第一次出现时触发一次 - 写错的表达式给中文说明(哪个字段、允许的范围),所写日期在所写月份里不存在的(2 月 30 日)直接拦下 - 描述覆盖每天、每周、每月、每年、每 N 小时 / 分钟这些常见写法,说不清的写「按 cron 表达式 x」,后面带时区 - 时区名对照时区库换成规范名:不区分大小写的文件系统上 asia/shanghai 也打得开,换到 Linux 就打不开了
This commit is contained in:
@@ -0,0 +1,376 @@
|
||||
"""五字段 cron:解析、下次 / 上次触发、中文描述。
|
||||
|
||||
自己写而不加依赖:要的只是五个字段(分 时 日 月 周)的标准写法,再加两条现成的库各有各的做法、说不清楚
|
||||
的规则——夏令时,和日、周都写了的时候取「或」还是「且」。
|
||||
|
||||
- 每个字段可写 *、列表(1,15)、范围(1-5)、步长(*/15、10-50/20、5/20),月和周可写英文缩写(JAN、MON),
|
||||
不分大小写;周日写 0 或 7。L、W、#、?、@daily 这些扩展写法不支持,报错说明
|
||||
- 日和周:两个都受限(都不以 * 开头)时,满足任一个就触发;有一个以 * 开头,就只看另一个。以 * 开头的步长
|
||||
(*/2)也算没受限——和 Linux 系统的 cron(Vixie / cronie)一致,同一个表达式在这里和在服务器上意思相同
|
||||
- 时间按任务时区的墙上时间匹配:夏令时拨快时跳过的本地时间(纽约 3 月的 02:30)那天不触发,不顺延;拨回时
|
||||
重复出现的本地时间(纽约 11 月的 01:30)只在第一次出现时触发一次
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
from datetime import date, datetime, timedelta, timezone
|
||||
from functools import lru_cache
|
||||
from zoneinfo import ZoneInfo, available_timezones
|
||||
|
||||
UTC = timezone.utc
|
||||
|
||||
#: 字段的键、界面上的叫法、取值范围
|
||||
_FIELDS = (
|
||||
("minute", "分", 0, 59),
|
||||
("hour", "时", 0, 23),
|
||||
("day", "日", 1, 31),
|
||||
("month", "月", 1, 12),
|
||||
("weekday", "周", 0, 7),
|
||||
)
|
||||
_ALLOWED = {
|
||||
"minute": "0–59",
|
||||
"hour": "0–23",
|
||||
"day": "1–31",
|
||||
"month": "1–12 或 JAN–DEC",
|
||||
"weekday": "0–7(0 和 7 都是周日)或 SUN–SAT",
|
||||
}
|
||||
_MONTH_NAMES = {name: i + 1 for i, name in enumerate(
|
||||
("JAN", "FEB", "MAR", "APR", "MAY", "JUN", "JUL", "AUG", "SEP", "OCT", "NOV", "DEC"))}
|
||||
_WEEKDAY_NAMES = {name: i for i, name in enumerate(("SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT"))}
|
||||
#: 每个月最多有几天:2 月按闰年算(2 月 29 日四年一次,不算永远不会触发)
|
||||
_MONTH_DAYS = {1: 31, 2: 29, 3: 31, 4: 30, 5: 31, 6: 30, 7: 31, 8: 31, 9: 30, 10: 31, 11: 30, 12: 31}
|
||||
#: 往后(往前)找触发时间最多找几年。2 月 29 日最长要等 8 年(2096 年之后是 2104 年)
|
||||
_HORIZON_YEARS = 9
|
||||
#: 夏令时一次最多拨动多少(历史上有过拨 2 小时的),往前找时据此跳过不可能的墙上时间
|
||||
_MAX_SHIFT = timedelta(hours=3)
|
||||
|
||||
_WEEKDAY_LABEL = {0: "周日", 1: "周一", 2: "周二", 3: "周三", 4: "周四", 5: "周五", 6: "周六"}
|
||||
|
||||
|
||||
class CronError(ValueError):
|
||||
"""表达式写错了。str() 是给人看的中文说明;field 是出错的字段(minute / hour / day / month / weekday),
|
||||
说的是整个表达式(字段个数不对、永远不会触发)时为 None。"""
|
||||
|
||||
def __init__(self, message: str, field: str | None = None) -> None:
|
||||
super().__init__(message)
|
||||
self.field = field
|
||||
|
||||
|
||||
class TimezoneError(ValueError):
|
||||
"""时区名认不出。str() 是给人看的中文说明。"""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class CronSpec:
|
||||
"""解析好的表达式。expr 是规范化后的原文(字段之间一个空格),描述、报错里引用它。"""
|
||||
|
||||
expr: str
|
||||
minutes: tuple[int, ...]
|
||||
hours: tuple[int, ...]
|
||||
days: frozenset[int]
|
||||
months: frozenset[int]
|
||||
#: 0 是周日,6 是周六(写 7 的已经换成 0)
|
||||
weekdays: frozenset[int]
|
||||
#: 日、周字段是不是以 * 开头(没受限)。两个都受限时取「或」
|
||||
day_star: bool
|
||||
weekday_star: bool
|
||||
|
||||
def matches_day(self, day: date) -> bool:
|
||||
if day.month not in self.months:
|
||||
return False
|
||||
in_days = day.day in self.days
|
||||
# date.weekday() 周一是 0;cron 周日是 0
|
||||
in_weekdays = (day.weekday() + 1) % 7 in self.weekdays
|
||||
if self.day_star or self.weekday_star:
|
||||
return in_days and in_weekdays
|
||||
return in_days or in_weekdays
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 解析
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
|
||||
def parse(expr: str | CronSpec) -> CronSpec:
|
||||
"""解析五字段表达式。写错抛 CronError(中文说明,指出字段和允许的范围)。"""
|
||||
if isinstance(expr, CronSpec):
|
||||
return expr
|
||||
parts = str(expr or "").split()
|
||||
if not parts:
|
||||
raise CronError("cron 表达式不能为空,需要 5 个字段(分 时 日 月 周),例如 0 9 * * 1 表示每周一 09:00")
|
||||
if len(parts) != 5:
|
||||
raise CronError(f"cron 表达式需要 5 个字段(分 时 日 月 周),用空格分隔;现在有 {len(parts)} 个")
|
||||
values = [_parse_field(text, *meta) for text, meta in zip(parts, _FIELDS)]
|
||||
spec = CronSpec(
|
||||
expr=" ".join(parts),
|
||||
minutes=tuple(sorted(values[0])),
|
||||
hours=tuple(sorted(values[1])),
|
||||
days=frozenset(values[2]),
|
||||
months=frozenset(values[3]),
|
||||
weekdays=frozenset(v % 7 for v in values[4]),
|
||||
day_star=parts[2].startswith("*"),
|
||||
weekday_star=parts[4].startswith("*"),
|
||||
)
|
||||
_refuse_never(spec)
|
||||
return spec
|
||||
|
||||
|
||||
def _parse_field(text: str, key: str, label: str, low: int, high: int) -> set[int]:
|
||||
out: set[int] = set()
|
||||
for item in text.split(","):
|
||||
if not item:
|
||||
raise CronError(f"「{label}」字段「{text}」里有空的列表项,允许 {_ALLOWED[key]}", key)
|
||||
out |= _parse_item(item, key, label, low, high)
|
||||
return out
|
||||
|
||||
|
||||
def _parse_item(item: str, key: str, label: str, low: int, high: int) -> set[int]:
|
||||
base, slash, step_text = item.partition("/")
|
||||
step = 1
|
||||
if slash:
|
||||
if not step_text.isdigit() or int(step_text) == 0:
|
||||
raise CronError(f"「{label}」字段「{item}」的步长需要是正整数,现在是「{step_text}」", key)
|
||||
step = int(step_text)
|
||||
if base == "*":
|
||||
start, end = low, high
|
||||
elif "-" in base:
|
||||
left, _, right = base.partition("-")
|
||||
start = _value(left, item, key, label, low, high)
|
||||
end = _value(right, item, key, label, low, high, range_end=True)
|
||||
if start > end:
|
||||
raise CronError(f"「{label}」字段的范围「{base}」起点大于终点", key)
|
||||
else:
|
||||
start = _value(base, item, key, label, low, high)
|
||||
# 「5/20」是从 5 到最大值、每 20 一个;不带步长就是这一个值
|
||||
end = high if slash else start
|
||||
if key == "weekday" and base == "*":
|
||||
end = 6 # * 是周日到周六,7 和 0 是同一天
|
||||
return set(range(start, end + 1, step))
|
||||
|
||||
|
||||
def _value(token: str, item: str, key: str, label: str, low: int, high: int, *, range_end: bool = False) -> int:
|
||||
word = token.strip().upper()
|
||||
if word.isdigit():
|
||||
number = int(word)
|
||||
if not low <= number <= high:
|
||||
raise CronError(f"「{label}」字段的 {number} 超出范围,允许 {_ALLOWED[key]}", key)
|
||||
return number
|
||||
names = _MONTH_NAMES if key == "month" else _WEEKDAY_NAMES if key == "weekday" else None
|
||||
if word.isalpha() and names is None:
|
||||
raise CronError(f"「{label}」字段不能使用英文缩写「{token}」,只有「月」和「周」字段可以,允许 {_ALLOWED[key]}", key)
|
||||
if names is not None and word in names:
|
||||
number = names[word]
|
||||
# MON-SUN 是周一到周日:范围终点的 SUN 当 7
|
||||
return 7 if key == "weekday" and range_end and number == 0 else number
|
||||
raise CronError(
|
||||
f"「{label}」字段无法识别「{item}」,允许 {_ALLOWED[key]},可以写 *、列表(1,15)、范围(1-5)和步长(*/10)", key)
|
||||
|
||||
|
||||
def _refuse_never(spec: CronSpec) -> None:
|
||||
"""日受限、周没受限时,所写的日子在所写的月份里一天都不存在(2 月 30 日、小月的 31 日)就永远不会触发。
|
||||
周受限时总有符合的那一天,不用查。"""
|
||||
if spec.day_star or not spec.weekday_star:
|
||||
return
|
||||
if any(day <= _MONTH_DAYS[month] for month in spec.months for day in spec.days):
|
||||
return
|
||||
raise CronError("这个 cron 表达式永远不会触发:所写的日期在所写的月份里不存在(例如 2 月没有 30 日)", "day")
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 时区
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
|
||||
@lru_cache(maxsize=1)
|
||||
def _zones() -> dict[str, str]:
|
||||
"""小写名 → 规范名。在不区分大小写的文件系统上 ZoneInfo("asia/shanghai") 也能打开,存进去的却不是规范名,
|
||||
换到 Linux 上就打不开了:一律对照时区库的清单换成规范名。"""
|
||||
return {name.lower(): name for name in available_timezones()}
|
||||
|
||||
|
||||
def timezone_name(name: str) -> str:
|
||||
"""规范的 IANA 时区名。认不出抛 TimezoneError。"""
|
||||
text = str(name or "").strip()
|
||||
canonical = _zones().get(text.lower()) if text else None
|
||||
if canonical is None:
|
||||
shown = f"「{text}」" if text else "(未填写)"
|
||||
raise TimezoneError(f"无法识别的时区{shown},请填写 IANA 时区名,例如 Asia/Shanghai")
|
||||
return canonical
|
||||
|
||||
|
||||
def zone(name: str | ZoneInfo) -> ZoneInfo:
|
||||
if isinstance(name, ZoneInfo):
|
||||
return name
|
||||
return ZoneInfo(timezone_name(name))
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 触发时间
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
|
||||
def _instant(local: datetime, tz: ZoneInfo) -> datetime | None:
|
||||
"""本地墙上时间 → UTC 时刻。拨快时跳过的本地时间不存在,返回 None;拨回时重复的取第一次出现(fold=0)。
|
||||
|
||||
zoneinfo 对不存在的本地时间按拨快前的偏移换算,换回本地就对不上原来的墙上时间——据此认出它。按 fold=0
|
||||
换算,本地时间越晚时刻也越晚,往后找到的第一个就是最早的那个。"""
|
||||
aware = local.replace(tzinfo=tz, fold=0)
|
||||
moment = aware.astimezone(UTC)
|
||||
if moment.astimezone(tz).replace(tzinfo=None) != local:
|
||||
return None
|
||||
return moment
|
||||
|
||||
|
||||
def _days(start: date, step: int, spec: CronSpec):
|
||||
"""从 start 起逐日往后(step=1)或往前(step=-1)走,只交出符合月、日、周的那些天。不在所写月份里的整月跳过。"""
|
||||
day = start
|
||||
limit = timedelta(days=366 * _HORIZON_YEARS)
|
||||
stop = start + limit if step > 0 else start - limit
|
||||
while (day <= stop) if step > 0 else (day >= stop):
|
||||
if day.month not in spec.months:
|
||||
if step > 0:
|
||||
day = (day.replace(day=1) + timedelta(days=32)).replace(day=1)
|
||||
else:
|
||||
day = day.replace(day=1) - timedelta(days=1)
|
||||
continue
|
||||
if spec.matches_day(day):
|
||||
yield day
|
||||
day += timedelta(days=step)
|
||||
|
||||
|
||||
def next_fire(expr: str | CronSpec, tz: str | ZoneInfo, after: datetime) -> datetime | None:
|
||||
"""after 之后(不含)最早的一次触发,UTC。找不到(只在夏令时把仅有的那几个时刻全跳过时)返回 None。"""
|
||||
spec, zone_info = parse(expr), zone(tz)
|
||||
after = _aware(after)
|
||||
local = after.astimezone(zone_info).replace(tzinfo=None)
|
||||
floor = local.replace(second=0, microsecond=0)
|
||||
for day in _days(local.date(), 1, spec):
|
||||
for hour in spec.hours:
|
||||
for minute in spec.minutes:
|
||||
candidate = datetime(day.year, day.month, day.day, hour, minute)
|
||||
# 墙上时间早于 after 的那一分钟,时刻必定也早于 after(拨回那天第二遍的 after 更是如此),不用换算
|
||||
if candidate < floor:
|
||||
continue
|
||||
moment = _instant(candidate, zone_info)
|
||||
if moment is not None and moment > after:
|
||||
return moment
|
||||
return None
|
||||
|
||||
|
||||
def prev_fire(expr: str | CronSpec, tz: str | ZoneInfo, before: datetime) -> datetime | None:
|
||||
"""before 之前(不含)最近的一次触发,UTC。拨回那天第二遍的时刻往前找,第一遍出现的同一本地时间算已经触发过。"""
|
||||
spec, zone_info = parse(expr), zone(tz)
|
||||
before = _aware(before)
|
||||
local = before.astimezone(zone_info).replace(tzinfo=None)
|
||||
for day in _days(local.date(), -1, spec):
|
||||
for hour in reversed(spec.hours):
|
||||
for minute in reversed(spec.minutes):
|
||||
candidate = datetime(day.year, day.month, day.day, hour, minute)
|
||||
# 只按时刻比较:第二遍的 01:40 之前,墙上时间更晚的第一遍 01:50 也算。超出夏令时最大拨动幅度的不可能
|
||||
if candidate > local + _MAX_SHIFT:
|
||||
continue
|
||||
moment = _instant(candidate, zone_info)
|
||||
if moment is not None and moment < before:
|
||||
return moment
|
||||
return None
|
||||
|
||||
|
||||
def last_due(expr: str | CronSpec, tz: str | ZoneInfo, at: datetime) -> datetime | None:
|
||||
"""at 之前(含)最近的一次触发,UTC。"""
|
||||
return prev_fire(expr, tz, _aware(at) + timedelta(microseconds=1))
|
||||
|
||||
|
||||
def preview(expr: str | CronSpec, tz: str | ZoneInfo, n: int = 5, *, after: datetime | None = None) -> list[datetime]:
|
||||
"""after(默认现在)之后的 n 次触发,UTC。"""
|
||||
spec, zone_info = parse(expr), zone(tz)
|
||||
out: list[datetime] = []
|
||||
cursor = _aware(after) if after is not None else datetime.now(UTC)
|
||||
while len(out) < n:
|
||||
moment = next_fire(spec, zone_info, cursor)
|
||||
if moment is None:
|
||||
break
|
||||
out.append(moment)
|
||||
cursor = moment
|
||||
return out
|
||||
|
||||
|
||||
def _aware(value: datetime) -> datetime:
|
||||
"""不带时区的按 UTC 算(库里读出来的都带,这里只防调用方传 naive 的)。"""
|
||||
return value if value.tzinfo is not None else value.replace(tzinfo=UTC)
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 中文描述
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
|
||||
def describe(expr: str | CronSpec, tz: str) -> str:
|
||||
"""「每周一 09:00(Asia/Shanghai)」。说不清的写「按 cron 表达式 x(时区)」。"""
|
||||
spec = parse(expr)
|
||||
return f"{_describe(spec) or f'按 cron 表达式 {spec.expr}'}({tz})"
|
||||
|
||||
|
||||
def _describe(spec: CronSpec) -> str | None:
|
||||
all_days = spec.days == frozenset(range(1, 32))
|
||||
all_weekdays = spec.weekdays == frozenset(range(7))
|
||||
all_months = spec.months == frozenset(range(1, 13))
|
||||
# 日、周都受限时取「或」:有一边是全部,那就是每天;两边都只写了一部分就说不清,交给兜底
|
||||
either = not (spec.day_star or spec.weekday_star)
|
||||
every_day = (all_days and all_weekdays) or (either and (all_days or all_weekdays))
|
||||
# 日写的 *(以 * 开头、且确实是全部日子)时只看周;周写的 * 时只看日。*/2 这种以 * 开头的步长不是全部
|
||||
weekly = not every_day and spec.day_star and all_days
|
||||
monthly = not every_day and spec.weekday_star and all_weekdays
|
||||
if every_day and all_months:
|
||||
if spec.minutes == tuple(range(60)) and spec.hours == tuple(range(24)):
|
||||
return "每分钟"
|
||||
step = _step_of(spec.minutes, 60)
|
||||
if step and spec.hours == tuple(range(24)):
|
||||
return f"每 {step} 分钟"
|
||||
if len(spec.minutes) != 1:
|
||||
return None
|
||||
minute = spec.minutes[0]
|
||||
if every_day and all_months:
|
||||
if spec.hours == tuple(range(24)):
|
||||
return "每小时整点" if minute == 0 else f"每小时第 {minute} 分钟"
|
||||
step = _step_of(spec.hours, 24)
|
||||
if step:
|
||||
return f"每 {step} 小时" if minute == 0 else f"每 {step} 小时(第 {minute} 分钟)"
|
||||
if len(spec.hours) > 4:
|
||||
return None
|
||||
times = "、".join(f"{hour:02d}:{minute:02d}" for hour in spec.hours)
|
||||
if every_day and all_months:
|
||||
return f"每天 {times}"
|
||||
if weekly and all_months:
|
||||
return f"每{_weekdays_text(spec.weekdays)} {times}"
|
||||
if not monthly or len(spec.days) > 4:
|
||||
return None
|
||||
days = "、".join(f"{day} 日" for day in sorted(spec.days))
|
||||
if all_months:
|
||||
return f"每月 {days} {times}"
|
||||
if len(spec.months) == 1:
|
||||
month = next(iter(spec.months))
|
||||
if month == 2 and spec.days == frozenset({29}):
|
||||
return f"每逢闰年 2 月 29 日 {times}"
|
||||
return f"每年 {month} 月 {days} {times}"
|
||||
return None
|
||||
|
||||
|
||||
def _step_of(values: tuple[int, ...], size: int) -> int | None:
|
||||
"""values 是不是从 0 起、每 n 一个、整除 size 的等差(*/n):是就返回 n(大于 1)。不整除的(*/7 分钟)到了
|
||||
整点会重新数,说成「每 7 分钟」就不对了。"""
|
||||
if len(values) < 2 or values[0] != 0:
|
||||
return None
|
||||
step = values[1] - values[0]
|
||||
if step <= 1 or size % step or values != tuple(range(0, size, step)):
|
||||
return None
|
||||
return step
|
||||
|
||||
|
||||
def _weekdays_text(weekdays: frozenset[int]) -> str:
|
||||
"""周一在前、周日在后。连续三天以上写「周一至周五」。"""
|
||||
ordered = sorted(weekdays, key=lambda d: (d - 1) % 7)
|
||||
positions = [(d - 1) % 7 for d in ordered]
|
||||
if len(ordered) >= 3 and positions == list(range(positions[0], positions[0] + len(positions))):
|
||||
return f"{_WEEKDAY_LABEL[ordered[0]]}至{_WEEKDAY_LABEL[ordered[-1]]}"
|
||||
return "、".join(_WEEKDAY_LABEL[d] for d in ordered)
|
||||
|
||||
@@ -0,0 +1,243 @@
|
||||
"""定时任务的 cron(app/scheduler/cron.py):自己写的五字段解析、下次触发、中文描述。
|
||||
|
||||
- 五个字段(分 时 日 月 周):*、列表、范围、步长、月份和星期的英文缩写;周日写 0 或 7
|
||||
- 日和周都受限时取「或」,有一个以 * 开头就只看另一个(和 Linux 系统的 cron 一致)
|
||||
- 下次触发按任务时区的墙上时间算:夏令时跳过的本地时间不触发,重复的本地时间只在第一次出现时触发一次
|
||||
- 写错的表达式给中文说明:哪个字段、允许的范围;永远不会触发的(2 月 30 日)也拦下
|
||||
- 描述:每天 09:00、每周一 09:00、每月 1 日 08:30、每 2 小时……说不清的写「按 cron 表达式 x」,后面带时区
|
||||
|
||||
America/New_York 2026 年 3 月 8 日 2:00 拨快到 3:00(2:00–2:59 不存在),11 月 1 日 2:00 拨回 1:00(1:00–1:59 出现两次)。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
from datetime import datetime, timedelta, timezone
|
||||
|
||||
import pytest
|
||||
|
||||
from app.scheduler import cron
|
||||
|
||||
UTC = timezone.utc
|
||||
NY = "America/New_York"
|
||||
|
||||
|
||||
def utc(*args: int) -> datetime:
|
||||
return datetime(*args, tzinfo=UTC)
|
||||
|
||||
|
||||
def nexts(expr: str, tz: str, after: datetime, n: int = 5) -> list[datetime]:
|
||||
return cron.preview(expr, tz, n, after=after)
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 解析:*、列表、范围、步长、缩写
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
|
||||
def test_star_list_range_step():
|
||||
spec = cron.parse("*/15 9-17 * * 1-5")
|
||||
assert spec.minutes == (0, 15, 30, 45)
|
||||
assert spec.hours == tuple(range(9, 18))
|
||||
assert spec.weekdays == frozenset({1, 2, 3, 4, 5})
|
||||
assert spec.days == frozenset(range(1, 32)) and spec.months == frozenset(range(1, 13))
|
||||
|
||||
|
||||
def test_range_with_step_and_value_with_step():
|
||||
assert cron.parse("10-50/20 * * * *").minutes == (10, 30, 50)
|
||||
# 「5/20」是 5 到最大值、每 20 一个(Vixie cron 的写法)
|
||||
assert cron.parse("5/20 * * * *").minutes == (5, 25, 45)
|
||||
assert cron.parse("0 0,12 1,15 * *").hours == (0, 12)
|
||||
|
||||
|
||||
def test_month_and_weekday_abbreviations_any_case():
|
||||
spec = cron.parse("0 9 * jan,Jul,DEC mon-fri")
|
||||
assert spec.months == frozenset({1, 7, 12})
|
||||
assert spec.weekdays == frozenset({1, 2, 3, 4, 5})
|
||||
# 周日写 0、7、SUN 都行;MON-SUN 是周一到周日
|
||||
assert cron.parse("0 9 * * 7").weekdays == frozenset({0})
|
||||
assert cron.parse("0 9 * * SUN,7").weekdays == frozenset({0})
|
||||
assert cron.parse("0 9 * * MON-SUN").weekdays == frozenset(range(7))
|
||||
assert cron.parse("0 9 * * 5-7").weekdays == frozenset({5, 6, 0})
|
||||
|
||||
|
||||
def test_expression_is_normalized():
|
||||
assert cron.parse(" 0 9 * *\t1 ").expr == "0 9 * * 1"
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 写错的表达式:中文说明,指出哪个字段、允许的范围
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
|
||||
@pytest.mark.parametrize("expr, fragments", [
|
||||
("", ["不能为空"]),
|
||||
("* * * *", ["5 个字段", "4 个"]),
|
||||
("0 9 * * 1 2026", ["5 个字段", "6 个"]),
|
||||
("61 * * * *", ["「分」", "61", "0–59"]),
|
||||
("0 24 * * *", ["「时」", "24", "0–23"]),
|
||||
("0 0 0 * *", ["「日」", "1–31"]),
|
||||
("0 0 * 13 *", ["「月」", "1–12"]),
|
||||
("0 0 * * 8", ["「周」", "0–7"]),
|
||||
("*/0 * * * *", ["「分」", "步长"]),
|
||||
("*/x * * * *", ["「分」", "步长"]),
|
||||
("0 20-10 * * *", ["「时」", "20-10", "起点大于终点"]),
|
||||
("0 JAN * * *", ["「时」", "JAN", "缩写"]),
|
||||
("0 9 * * L", ["「周」", "L"]),
|
||||
("0 9 1,,2 * *", ["「日」"]),
|
||||
("@daily", ["5 个字段"]),
|
||||
])
|
||||
def test_invalid_expressions_explain_in_chinese(expr, fragments):
|
||||
with pytest.raises(cron.CronError) as caught:
|
||||
cron.parse(expr)
|
||||
message = str(caught.value)
|
||||
for fragment in fragments:
|
||||
assert fragment in message, message
|
||||
|
||||
|
||||
def test_invalid_expression_names_the_field():
|
||||
with pytest.raises(cron.CronError) as caught:
|
||||
cron.parse("0 25 * * *")
|
||||
assert caught.value.field == "hour"
|
||||
|
||||
|
||||
@pytest.mark.parametrize("expr", ["0 0 30 2 *", "0 0 31 4,6,9,11 *", "0 0 31 FEB *"])
|
||||
def test_dates_that_never_exist_are_rejected(expr):
|
||||
with pytest.raises(cron.CronError) as caught:
|
||||
cron.parse(expr)
|
||||
assert "永远不会触发" in str(caught.value)
|
||||
|
||||
|
||||
def test_leap_day_is_not_never():
|
||||
"""2 月 29 日四年一次,不算永远不会触发。日、周都受限时周那一边总会碰上,也不算"""
|
||||
cron.parse("0 0 29 2 *")
|
||||
cron.parse("0 0 30 2 1")
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 下次触发
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
|
||||
def test_next_is_strictly_after():
|
||||
assert cron.next_fire("0 9 * * *", "UTC", utc(2026, 10, 5, 9, 0)) == utc(2026, 10, 6, 9, 0)
|
||||
assert cron.next_fire("0 9 * * *", "UTC", utc(2026, 10, 5, 8, 59, 59)) == utc(2026, 10, 5, 9, 0)
|
||||
|
||||
|
||||
def test_next_follows_the_task_timezone():
|
||||
# 上海 09:00 = UTC 01:00
|
||||
assert cron.next_fire("0 9 * * *", "Asia/Shanghai", utc(2026, 10, 5, 2, 0)) == utc(2026, 10, 6, 1, 0)
|
||||
|
||||
|
||||
def test_weekly_and_monthly():
|
||||
# 2026-10-05 是周一
|
||||
assert nexts("0 9 * * 1", "UTC", utc(2026, 10, 5, 9, 0), 2) == [utc(2026, 10, 12, 9), utc(2026, 10, 19, 9)]
|
||||
assert nexts("30 8 1 * *", "UTC", utc(2026, 10, 5), 3) == [
|
||||
utc(2026, 11, 1, 8, 30), utc(2026, 12, 1, 8, 30), utc(2027, 1, 1, 8, 30)]
|
||||
|
||||
|
||||
def test_day_and_weekday_both_restricted_means_either():
|
||||
"""每月 1 日或者每周一:11 月 1 日是周日,也触发"""
|
||||
assert nexts("0 9 1 * 1", "UTC", utc(2026, 10, 5, 10), 5) == [
|
||||
utc(2026, 10, 12, 9), utc(2026, 10, 19, 9), utc(2026, 10, 26, 9), utc(2026, 11, 1, 9), utc(2026, 11, 2, 9)]
|
||||
|
||||
|
||||
def test_star_on_one_side_means_only_the_other():
|
||||
assert nexts("0 9 * * 1", "UTC", utc(2026, 10, 25), 2) == [utc(2026, 10, 26, 9), utc(2026, 11, 2, 9)]
|
||||
assert nexts("0 9 1 * *", "UTC", utc(2026, 10, 25), 2) == [utc(2026, 11, 1, 9), utc(2026, 12, 1, 9)]
|
||||
# 以 * 开头的步长也算「没限定」(和 Linux 系统的 cron 一致):单数日里的周一,不是单数日或周一
|
||||
assert nexts("0 9 */2 * 1", "UTC", utc(2026, 10, 1), 3) == [
|
||||
utc(2026, 10, 5, 9), utc(2026, 10, 19, 9), utc(2026, 11, 9, 9)]
|
||||
|
||||
|
||||
def test_leap_day_every_four_years():
|
||||
assert cron.next_fire("0 0 29 2 *", "UTC", utc(2026, 1, 1)) == utc(2028, 2, 29)
|
||||
assert cron.next_fire("0 0 29 2 *", "UTC", utc(2028, 2, 29)) == utc(2032, 2, 29)
|
||||
# 按任务时区:上海的 2 月 29 日零点是 UTC 2 月 28 日 16:00
|
||||
assert cron.next_fire("0 0 29 2 *", "Asia/Shanghai", utc(2026, 1, 1)) == utc(2028, 2, 28, 16)
|
||||
|
||||
|
||||
def test_spring_forward_skips_the_missing_local_time():
|
||||
"""3 月 8 日没有 02:30:那天不触发,下一次是 3 月 9 日 02:30(夏令时,UTC 06:30)"""
|
||||
assert nexts("30 2 * * *", NY, utc(2026, 3, 7, 8), 2) == [utc(2026, 3, 9, 6, 30), utc(2026, 3, 10, 6, 30)]
|
||||
# 每半小时:01:30(冬令时)之后是 03:00(夏令时),02:00、02:30 不存在
|
||||
assert nexts("*/30 * * * *", NY, utc(2026, 3, 8, 6, 15), 3) == [
|
||||
utc(2026, 3, 8, 6, 30), utc(2026, 3, 8, 7, 0), utc(2026, 3, 8, 7, 30)]
|
||||
# 拨快之后的 03:00 照常触发
|
||||
assert cron.next_fire("0 3 * * *", NY, utc(2026, 3, 8, 5)) == utc(2026, 3, 8, 7)
|
||||
|
||||
|
||||
def test_fall_back_fires_the_repeated_local_time_once():
|
||||
"""11 月 1 日 01:30 出现两次(UTC 05:30 夏令时、06:30 冬令时):只在第一次触发"""
|
||||
assert nexts("30 1 * * *", NY, utc(2026, 11, 1, 4), 2) == [utc(2026, 11, 1, 5, 30), utc(2026, 11, 2, 6, 30)]
|
||||
# 每半小时:01:00、01:30 各一次,第二遍的 01:00、01:30 不再触发,下一次是 02:00(冬令时,UTC 07:00)
|
||||
assert nexts("*/30 * * * *", NY, utc(2026, 11, 1, 4, 45), 4) == [
|
||||
utc(2026, 11, 1, 5, 0), utc(2026, 11, 1, 5, 30), utc(2026, 11, 1, 7, 0), utc(2026, 11, 1, 7, 30)]
|
||||
# 从第二遍的 01:10(UTC 06:10)往后找:01:30 已经在第一遍触发过
|
||||
assert cron.next_fire("*/30 * * * *", NY, utc(2026, 11, 1, 6, 10)) == utc(2026, 11, 1, 7, 0)
|
||||
|
||||
|
||||
def test_previous_fire():
|
||||
assert cron.prev_fire("0 9 * * 1", "UTC", utc(2026, 10, 5, 9)) == utc(2026, 9, 28, 9)
|
||||
assert cron.prev_fire("0 9 * * 1", "UTC", utc(2026, 10, 5, 9, 0, 1)) == utc(2026, 10, 5, 9)
|
||||
# 第二遍的 01:40 之前最近的一次是第一遍的 01:30(UTC 05:30),它已经发生过
|
||||
assert cron.prev_fire("30 1 * * *", NY, utc(2026, 11, 1, 6, 40)) == utc(2026, 11, 1, 5, 30)
|
||||
assert cron.prev_fire("30 2 * * *", NY, utc(2026, 3, 9, 0)) == utc(2026, 3, 7, 7, 30)
|
||||
|
||||
|
||||
def test_last_due_at_or_before():
|
||||
assert cron.last_due("*/5 * * * *", "UTC", utc(2026, 10, 5, 9, 7, 30)) == utc(2026, 10, 5, 9, 5)
|
||||
assert cron.last_due("*/5 * * * *", "UTC", utc(2026, 10, 5, 9, 5)) == utc(2026, 10, 5, 9, 5)
|
||||
|
||||
|
||||
def test_preview_counts_and_defaults_to_now():
|
||||
out = cron.preview("*/10 * * * *", "UTC", 3)
|
||||
assert len(out) == 3 and all(b - a == timedelta(minutes=10) for a, b in zip(out, out[1:]))
|
||||
assert out[0] > datetime.now(UTC) - timedelta(seconds=1)
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 时区
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
|
||||
def test_timezone_names_are_canonical():
|
||||
assert cron.timezone_name("Asia/Shanghai") == "Asia/Shanghai"
|
||||
assert cron.timezone_name(" asia/shanghai ") == "Asia/Shanghai"
|
||||
assert cron.timezone_name("UTC") == "UTC"
|
||||
|
||||
|
||||
@pytest.mark.parametrize("name", ["", "Mars/Olympus", "../etc/passwd", "GMT+8 北京"])
|
||||
def test_unknown_timezone_explains_in_chinese(name):
|
||||
with pytest.raises(cron.TimezoneError) as caught:
|
||||
cron.timezone_name(name)
|
||||
assert "时区" in str(caught.value) and "Asia/Shanghai" in str(caught.value)
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# 中文描述
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
|
||||
@pytest.mark.parametrize("expr, text", [
|
||||
("0 9 * * *", "每天 09:00"),
|
||||
("0 9,18 * * *", "每天 09:00、18:00"),
|
||||
("0 9 * * 1", "每周一 09:00"),
|
||||
("0 9 * * MON", "每周一 09:00"),
|
||||
("0 9 * * 1,3,5", "每周一、周三、周五 09:00"),
|
||||
("0 9 * * 1-5", "每周一至周五 09:00"),
|
||||
("0 10 * * 0", "每周日 10:00"),
|
||||
("30 8 1 * *", "每月 1 日 08:30"),
|
||||
("30 8 1,15 * *", "每月 1 日、15 日 08:30"),
|
||||
("0 8 1 3 *", "每年 3 月 1 日 08:00"),
|
||||
("0 0 29 2 *", "每逢闰年 2 月 29 日 00:00"),
|
||||
("0 */2 * * *", "每 2 小时"),
|
||||
("15 */6 * * *", "每 6 小时(第 15 分钟)"),
|
||||
("0 * * * *", "每小时整点"),
|
||||
("20 * * * *", "每小时第 20 分钟"),
|
||||
("*/5 * * * *", "每 5 分钟"),
|
||||
("* * * * *", "每分钟"),
|
||||
("0 9 1 * 1", "按 cron 表达式 0 9 1 * 1"),
|
||||
("*/7 * * * *", "按 cron 表达式 */7 * * * *"),
|
||||
("0 9-17 * * 1-5", "按 cron 表达式 0 9-17 * * 1-5"),
|
||||
])
|
||||
def test_describe_in_chinese(expr, text):
|
||||
assert cron.describe(expr, "Asia/Shanghai") == f"{text}(Asia/Shanghai)"
|
||||
Reference in New Issue
Block a user