croniter Python 6.0.0 完整使用指南:cron 表达式解析、匹配时间计算与时区/DST 处理

原创2026-10-09 18:45:531,708 阅读

croniter Python 6.0.0 完整使用指南:cron 表达式解析、匹配时间计算与时区/DST 处理

croniter 是一个纯 Python 的 cron 表达式解析与调度时间计算库,它不做任务执行,只负责回答“下一次匹配时间是几点”。本文以 context-hub 仓库中维护的 croniter Python 包指南 为骨架,结合仓库的文档组织与 CLI 读取机制,系统讲解 6.0.0 版本的安装、核心 API(get_next/get_prev/all_next/croniter_range)、5/6/7 字段表达式、DOM/DOW 组合语义、时区与夏令时处理以及异常与实战陷阱,读完即可在自己的调度代码中正确落地 cron 计算。

这篇文档在仓库中的定位

在 context-hub 中,这份指南以多语言文档的形式存放于 content/croniter/docs/package/python/DOC.md,其 frontmatter 标明了版本 6.0.0、语言 python 与关键词 croniter,cron,python,scheduling,datetime,timezones。按照 内容指南 的目录约定(author/docs/entry-name/language/DOC.md),它对应一个名为 croniter/package 的 Python 语言文档条目,编程 Agent 可以通过 chub CLI 直接拉取:

chub get croniter/package --lang py

CLI 端到端解析语言/版本的逻辑位于 registry.js:当只有一个语言变体时自动推断,否则按 --lang 精确匹配。因此这份文档是面向 LLM/Agent 的“最小可用知识包”——它刻意保持短小、聚焦、可直接转化为代码,而不是替代官方手册。

Golden Rule:只算时间,不执行任务

使用 croniter 的第一原则是:用它计算调度时间,而不是让它替你跑任务。它只负责解析 cron 表达式并计算匹配的时间点,任务执行(如 while True: sleep 循环、分布式调度器、消息队列投递)由你的应用代码负责。

在 6.0.0 版本中,有三个最影响日常使用的默认行为,务必记牢:

  1. 传入 datetime 基准时间,而不是字符串或时间戳,迭代器的语义才清晰;
  2. 优先使用带时区(timezone-aware)的 datetime,返回结果会保留时区信息,避免浮动的本地时钟造成的跨时区错误;
  3. 显式设置 ret_type=datetime,否则默认返回的是 UNIX 时间戳 float,后续代码很容易踩类型坑。

文档还明确说明:croniter 没有包级认证、没有服务账号配置、没有必需的环境变量——它就是一个纯粹的解析与计算库,安装即用。

安装与版本钉定

croniter 通过 PyPI 分发,建议在项目中钉定精确版本,保证调度行为可复现:

python -m pip install "croniter==6.0.0"

常用替代安装方式:

uv add "croniter==6.0.0"
poetry add "croniter==6.0.0"

核心用法:构造迭代器并取相邻匹配

最基础的用法是用「cron 表达式 + 基准时间」构造 croniter 对象,然后调用 get_next() 取下一次匹配、get_prev() 取上一次匹配、get_current() 取当前基准:

from datetime import datetime
from zoneinfo import ZoneInfo

from croniter import croniter

base = datetime(2026, 3, 12, 9, 0, tzinfo=ZoneInfo("UTC"))

schedule = croniter(
    "*/15 * * * *",
    base,
    ret_type=datetime,
)

current = schedule.get_current(datetime)
next_run = schedule.get_next()
after_that = schedule.get_next()
previous_run = schedule.get_prev()

print(current)      # 2026-03-12 09:00:00+00:00
print(next_run)     # 2026-03-12 09:15:00+00:00
print(after_that)   # 2026-03-12 09:30:00+00:00
print(previous_run) # 2026-03-12 09:15:00+00:00

要点解读:

  • 每调用一次 get_next(),迭代器内部状态前进一步,所以连续两次调用分别得到 09:15 与 09:30;
  • get_prev() 从基准时间向前回溯,得到 09:15(即基准之前最近的一次匹配);
  • 如果省略 ret_type=datetime,get_next()/get_prev() 返回的是 float 形式的 UNIX 时间戳。这是新用户最常见的坑,下文“错误与实战陷阱”一节还会再次强调。

用生成器批量迭代未来/过去的匹配

当你想一次性拿到一串匹配时间(而不是反复调用 get_next())时,使用 all_next() 或 all_prev()。它们返回生成器,配合 enumerate 可以边遍历边计数:

from datetime import datetime
from zoneinfo import ZoneInfo

from croniter import croniter

base = datetime(2026, 3, 12, 0, 0, tzinfo=ZoneInfo("UTC"))
schedule = croniter("@daily", base, ret_type=datetime)

for index, run_at in enumerate(schedule.all_next(datetime), start=1):
    print(index, run_at)
    if index == 3:
        break

@ 开头的预定义别名在此版本中可用:

  • @midnight、@daily —— 每天零点;
  • @hourly —— 每小时整点;
  • @weekly —— 每周一零点(周起始);
  • @monthly —— 每月 1 号零点;
  • @yearly、@annually —— 每年 1 月 1 日零点。

校验表达式与区间匹配

当 cron 字符串来自用户输入或配置文件时,先校验再使用;当需要判断某个时间窗口内是否存在匹配时,用区间匹配。三个类方法覆盖这两类场景:

from datetime import datetime, timedelta
from zoneinfo import ZoneInfo

from croniter import croniter

candidate = datetime(2026, 3, 13, 9, 0, tzinfo=ZoneInfo("UTC"))

is_valid = croniter.is_valid("0 9 * * 1-5")
matches_exact_time = croniter.match("0 9 * * 1-5", candidate)
matches_within_hour = croniter.match_range(
    "0 9 * * 1-5",
    candidate,
    candidate + timedelta(hours=1),
)

print(is_valid)
print(matches_exact_time)
print(matches_within_hour)
  • is_valid(expr):只校验表达式语法是否合法,返回布尔值,适合在持久化用户配置前做闸门;
  • match(expr, date):判断某个精确时间点是否命中该表达式;
  • match_range(expr, start, end):判断 [start, end) 时间窗口内是否存在至少一次匹配,适合做“这个时段内有没有计划任务”类的查询。

用 croniter_range 枚举一个窗口内的所有匹配

当需要“两个端点之间的每一个匹配时间”时,croniter_range() 是最直接的入口——它把区间枚举变成一次可迭代的调用:

from datetime import datetime
from zoneinfo import ZoneInfo

from croniter import croniter_range

start = datetime(2026, 3, 16, 0, 0, tzinfo=ZoneInfo("UTC"))
stop = datetime(2026, 3, 16, 23, 59, tzinfo=ZoneInfo("UTC"))

for run_at in croniter_range(
    start,
    stop,
    "0 9,13,17 * * 1-5",
    ret_type=datetime,
):
    print(run_at)

行为细节:

  • 默认包含恰好落在 start 和 stop 端点上的匹配值;
  • 传入 exclude_ends=True 可以排除恰好等于端点的匹配。

这个 API 适合生成报表、日历视图,或者为“未来 N 次运行”之外的业务需求做预计算。

表达式特性:5/6/7 字段与秒的位置

croniter 6.0.0 接受恰好 5、6 或 7 个字段:

字段数 语义
5 字段 标准 cron:分、时、日(月)、月、周(星期几)
6 字段 在 5 字段基础上追加秒
7 字段 追加秒和年

默认情况下,秒是最后一个时间字段。 对 6 字段表达式而言,顺序是 分 时 日 月 星期 秒:

from datetime import datetime
from zoneinfo import ZoneInfo

from croniter import croniter

base = datetime(2026, 3, 12, 12, 0, tzinfo=ZoneInfo("UTC"))

# 12:00:30 every day
schedule = croniter("0 12 * * * 30", base, ret_type=datetime)
print(schedule.get_next())

如果你的表达式把秒放在开头(Quartz 风格),传入 second_at_beginning=True:

from datetime import datetime
from zoneinfo import ZoneInfo

from croniter import croniter

base = datetime(2026, 3, 12, 12, 0, tzinfo=ZoneInfo("UTC"))

# 12:00:30 every day, Quartz-style seconds-first order
schedule = croniter(
    "30 0 12 * * *",
    base,
    ret_type=datetime,
    second_at_beginning=True,
)
print(schedule.get_next())

其他常用解析特性(本指南明确列出):

  • 月份名与星期名:如 jan、mon-fri,可读性更好;
  • l(小写 L):在日(月)字段中表示“该月最后一天”;
  • 2#3 风格的第 N 个星期几:在星期字段中表示“该月第 3 个周二”这类语法;
  • ?:在日(月)或星期字段中与 * 等价,兼容 Quartz 习惯。

日(月)与星期组合:OR 与 AND 语义

当同时限定 day-of-month 和 day-of-week 时,croniter 默认采用 OR 语义(任一条件命中即触发)。这与许多调度器(尤其是 Quartz 风格)的 AND 语义不同,是最容易产生“意外调度”的坑之一。需要 AND 语义时,设置 day_or=False:

from datetime import datetime
from zoneinfo import ZoneInfo

from croniter import croniter

base = datetime(2026, 3, 1, 0, 0, tzinfo=ZoneInfo("UTC"))

# Fires when either condition matches: first day of the month OR Monday
either_rule = croniter(
    "0 9 1 * mon",
    base,
    ret_type=datetime,
)

# Fires only when both conditions match: first day of the month AND Monday
both_rules = croniter(
    "0 9 1 * mon",
    base,
    ret_type=datetime,
    day_or=False,
)

判断标准:表达式 0 9 1 * mon 默认会在“每月 1 号”或“任意周一”触发;而 day_or=False 后只在“既是 1 号又是周一”的日子触发。跨语言迁移调度配置(例如从 Quartz 或其它调度平台迁移到 croniter)时,务必先确认目标系统的 DOM/DOW 组合语义,否则会凭空多出或漏掉运行。

时区与夏令时(DST)

当基准时间是带时区的 datetime 时,croniter 会把时区信息保留在返回的 datetime 上。对于必须跟随真实时区(而非浮动本地时钟)的应用调度,应使用 aware datetime:

from datetime import datetime
from zoneinfo import ZoneInfo

from croniter import croniter

base = datetime(2026, 3, 29, 0, 30, tzinfo=ZoneInfo("Europe/Berlin"))
schedule = croniter("0 * * * *", base, ret_type=datetime)

for _ in range(3):
    print(schedule.get_next())

值得注意的工程结论(文档明确建议):

  • 如果你在意 DST 切换造成的“缺失或重复的小时”,优先全程使用 UTC;
  • 只有业务规则确实依赖本地墙钟时间(如“当地早晨 8 点”而非“UTC 8 点”)时,才使用具体时区;
  • 返回的 datetime 保留 tzinfo,这让你可以在业务层自行决定展示本地时间还是统一转 UTC。

异常与实战陷阱

当 cron 字符串来自用户或配置文件时,应捕获包级异常而不是裸奔:

from datetime import datetime
from zoneinfo import ZoneInfo

from croniter import CroniterBadCronError, CroniterBadDateError, croniter

base = datetime(2026, 3, 12, 0, 0, tzinfo=ZoneInfo("UTC"))

try:
    schedule = croniter(
        "0 4 1 1 fri",
        base,
        ret_type=datetime,
        day_or=False,
        max_years_between_matches=10,
    )
    print(schedule.get_next())
except CroniterBadCronError as exc:
    print(f"Invalid cron expression: {exc}")
except CroniterBadDateError as exc:
    print(f"No matching date found in search window: {exc}")
  • CroniterBadCronError:表达式语法不合法时抛出;
  • CroniterBadDateError:在给定的搜索窗口内找不到匹配日期时抛出(例如 0 4 1 1 fri 配合 day_or=False 这样的组合约束可能长时间无匹配)。

需要牢记的行为细节汇总:

行为 默认值 调整方式
get_next()/get_prev() 返回类型 float(UNIX 时间戳) 构造时传 ret_type=datetime
稀疏表达式的最大搜索年限 50 年 max_years_between_matches=<N> 收紧失败窗口
croniter_range() 是否包含端点 包含匹配端点 exclude_ends=True
哈希定义(如 h 字段) 需要 hash_id=... 传入 hash_id 才可用
6/7 字段中秒的位置 秒在末尾 second_at_beginning=True 改为秒开头
DOM 与 DOW 同时限定的组合语义 OR day_or=False 改为 AND

最小可复用 App 模式

对大多数应用而言,用一个极小的辅助函数把“表达式 → 下次运行时间”收敛成统一约定,能让整个代码库的调度逻辑保持一致:

from datetime import datetime
from zoneinfo import ZoneInfo

from croniter import croniter

UTC = ZoneInfo("UTC")

def next_run(cron_expression: str, now: datetime | None = None) -> datetime:
    base = now or datetime.now(UTC)
    return croniter(cron_expression, base, ret_type=datetime).get_next()

run_at = next_run("*/10 * * * *")
print(run_at)

这个模式的三个好处:

  1. 强制 aware datetime:默认基准取 datetime.now(UTC),从源头避免 naive datetime 参与调度比较;
  2. 强制 ret_type=datetime:从根上杜绝“拿到 float 时间戳再手动转换”的常见失误;
  3. 收敛异常处理点:后续若需加校验、加日志、加 max_years_between_matches,只需改这一个函数。

总结与落地清单

在代码中落地 croniter 6.0.0 时,按以下清单核对即可避开绝大多数坑:

  • ✅ 钉定版本安装:pip install "croniter==6.0.0"(或 uv add / poetry add);
  • ✅ 传入 datetime 基准,优先 ZoneInfo 指定时区的 aware datetime;
  • ✅ 构造时显式 ret_type=datetime,除非你确实需要 UNIX 时间戳 float;
  • ✅ 用户输入的表达式先过 croniter.is_valid(),再持久化;
  • ✅ 区间查询用 croniter_range(),注意端点默认包含,exclude_ends=True 可排除;
  • ✅ 6/7 字段注意秒的位置(默认在末尾,Quartz 风格用 second_at_beginning=True);
  • ✅ DOM 与 DOW 同时限定默认是 OR,需要 AND 时加 day_or=False;
  • ✅ 跨时区业务全程 UTC,只有强依赖本地墙钟时间时才用具体时区;
  • ✅ 捕获 CroniterBadCronError 与 CroniterBadDateError,稀疏表达式按需调小 max_years_between_matches;
  • ✅ 用一个 next_run(expr, now) 辅助函数统一调度入口。

这份指南由 context-hub 维护在 content/croniter/docs/package/python/DOC.md,Agent 可通过 chub get croniter/package --lang py 获取;仓库的 README 与 CLI 参考 说明了 chub 的完整使用方式,内容指南 则展示了这类版本化、语言化文档的组织规范,方便你为其他包贡献同类高质量指南。

登录后查看全文
context-hub