diff --git a/backend/app/scheduler/cron.py b/backend/app/scheduler/cron.py new file mode 100644 index 00000000..c944b671 --- /dev/null +++ b/backend/app/scheduler/cron.py @@ -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) + diff --git a/backend/tests/test_scheduler_cron.py b/backend/tests/test_scheduler_cron.py new file mode 100644 index 00000000..005f9e60 --- /dev/null +++ b/backend/tests/test_scheduler_cron.py @@ -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)"