croniter Python 6.0.0 完整使用指南:cron 表达式解析、匹配时间计算与时区/DST 处理
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 版本中,有三个最影响日常使用的默认行为,务必记牢:
- 传入
datetime基准时间,而不是字符串或时间戳,迭代器的语义才清晰; - 优先使用带时区(timezone-aware)的
datetime,返回结果会保留时区信息,避免浮动的本地时钟造成的跨时区错误; - 显式设置
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)
这个模式的三个好处:
- 强制 aware datetime:默认基准取
datetime.now(UTC),从源头避免 naive datetime 参与调度比较; - 强制
ret_type=datetime:从根上杜绝“拿到 float 时间戳再手动转换”的常见失误; - 收敛异常处理点:后续若需加校验、加日志、加
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 的完整使用方式,内容指南 则展示了这类版本化、语言化文档的组织规范,方便你为其他包贡献同类高质量指南。