Ruff 规则 DTZ007（call-datetime-strptime-without-zone）深度解析：拦截 `strptime` 产生的 naive datetime 及其文档化测试实践

导读

DTZ007 是 Ruff 中来自 flake8-datetimez 系列的一条时区安全 lint 规则，用于检测 datetime.datetime.strptime() 调用链最终产出的 naive（无时区）datetime 对象，并引导开发者显式补上 tzinfo 或调用 astimezone() 完成时区转换。本文以仓库内 规则的行为规范与可执行测试文档 为主线，结合其 Rust 源码实现、Python 测试 fixture 与快照，讲解 DTZ007 的检出逻辑、各种边界场景、修复方式以及 Ruff 独特的"Markdown 即测试"（mdtest）机制。读完本文，你将能准确判断哪些 strptime 调用链会被该规则报警、哪些写法可以安全绕过，并理解该文档如何在 Ruff 测试体系中被逐字执行。

DTZ007 规则速览：检出什么、为何需要

Ruff 官方源码对该规则的文档注释（docstring）给出了权威定义：

• 功能：检查 datetime.datetime.strptime() 的用法，凡是最终会得到 naive datetime 对象的调用都会被报告（规则定义文件）。
• 原因：Python 的 datetime 对象分为 naive 与 aware 两种。aware 对象能表达一个确定的时刻（在时间轴上可唯一定位），而 naive 对象缺少与其它 datetime 对象比较所需的时区信息，容易引发跨时区计算的隐蔽 bug，因此官方建议始终使用 aware 对象。而 strptime() 在格式串不含 %z 时返回的一定是 naive 对象，需要开发者主动通过 .replace(tzinfo=<timezone>) 或 .astimezone() 为其补充时区语义。
• 规则元数据：该规则注册名为 call-datetime-strptime-without-zone，规则码为 DTZ007，自 v0.0.188 起稳定，归类为 Pedantic（需要显式选用）类别（见 规则定义文件）。该规则当前未提供可自动应用的 fix，仅在源码中实现了 fix_title（修复建议文案），需要开发者手动改写代码。

启用方式：配置 lint.select

DTZ007 属于 Pedantic 类别，不会被任意"默认规则集"或 E/F 之类的前缀批量开启，必须显式选择。规范文档中给出了最小启用配置：

lint.select = ["DTZ007"]

放在 pyproject.toml 中即为：

[tool.ruff]
lint.select = ["DTZ007"]

等价地，也可以在命令行直接指定：

ruff check --select DTZ007 path/to/your/code.py

需要说明的是：这里的 TOML 配置块并非普通示例——mdtest 解析器会把文档中的 toml 代码块真正反序列化为该测试文件的 lint 配置（validate_config 会校验其合法性），也就是说这段配置在测试时真实生效（详见后文"mdtest 机制"）。

判定边界：什么样的调用链会被报告

DTZ007 的报警对象不是孤立的 strptime 调用，而是"以 strptime 为起点的一整条方法链"。规范文档用三个小节精确刻画了报警与豁免两种状态，每个代码块下方的 # error: [call-datetime-strptime-without-zone] 行内注释即预期诊断标记（无该标记的代码块预期零报警）。下面逐一解读。

场景一：先 replace 字段、后接 astimezone —— 不报警

文档明确指出："即使前面有一个或多个 replace 调用，只要最终调用 astimezone，产出的就是 aware datetime"：

from datetime import datetime, timezone

datetime.strptime("2026", "%Y").replace(microsecond=0).astimezone()
datetime.strptime("2026", "%Y").replace(hour=12).replace(minute=30).astimezone(timezone.utc)
datetime.strptime("2026", "%Y").replace(tzinfo=None).astimezone()

三种写法均被放行。它们共同点是：链的终点是 astimezone()——即使中间出现过 replace(tzinfo=None) 这种会把 tzinfo 抹掉的步骤，甚至 astimezone() 不带任何参数，Ruff 也认为最终对象已被转换为 aware。这与源码中的短路逻辑一致：分析器会先检查当前调用链是否"被 astimezone 跟随"（helpers::followed_by_astimezone，见 flake8-datetimez 辅助函数），若成立则直接 return，不再继续判定（规则实现）。

场景二：仅做字段替换、未做时区转换 —— 报警

"不含时区转换的替换，仍然产出 naive datetime"，因此下面两行各报一条 DTZ007：

from datetime import datetime

datetime.strptime("2026", "%Y").replace(microsecond=0)  # error: [call-datetime-strptime-without-zone]
datetime.strptime("2026", "%Y").replace(tzinfo=None)  # error: [call-datetime-strptime-without-zone]

值得注意第二行的特殊之处：虽然它给 replace 传了 tzinfo 参数，但值却是 None——把 tzinfo 显式置空，效果等同于不转换。源码为这两种情形设计了两套不同的诊断消息（规则定义文件）：

• 普通裸调用/无 tzinfo 的 replace：报 Naive datetime constructed using datetime.datetime.strptime() without %z；
• replace(tzinfo=None)：报 `datetime.datetime.strptime(...).replace(tz=None)` used。

对应的修复建议文案也区分两种：前者建议 Call .replace(tzinfo=<timezone>) or .astimezone() to convert to an aware datetime，后者建议 Pass a datetime.timezone object to the tzinfo parameter。

场景三：把 replace 方法"传给"另一个调用 —— 报警

最后一种边界情况是把 strptime 结果的方法本身作为参数传递：

from datetime import datetime

def convert(converter):
    converter.replace(datetime.strptime("2026", "%Y").replace).astimezone()  # error: [call-datetime-strptime-without-zone]

文档给出的解释是："把 replace 方法传给另一个对象的方法并不会转换被解析出的 datetime"。这里 datetime.strptime(...).replace 只是取出了一个未绑定方法引用并塞进 converter.replace(...) 的参数中，方法从未在 naive 结果上执行，astimezone 作用在 converter 的返回值上，与 strptime 结果毫无关系——因此照样报警。这提醒我们：DTZ007 的豁免判断只沿 strptime 调用自身所在的链进行，"链外"的任何方法调用都无法为其"洗白"。

源码级原理：DTZ007 的检出五步

从 规则实现 看，call_datetime_strptime_without_zone(checker, call) 的处理顺序是：

1. 模块门禁：语义分析器（semantic model）中若从未出现过 datetime 模块（seen_module(Modules::DATETIME)），直接返回（L91-L93）。因此 import datetime 或 from datetime import datetime 等导入必须真实存在于当前文件，规则才会生效。
2. 全限定名匹配：通过 resolve_qualified_name 把被调用函数解析为规范路径，只有段序列恰为 ["datetime", "datetime", "strptime"] 时才继续（L95-L106）。由于解析发生在限定名层面，datetime.datetime.strptime(...) 与 from datetime import datetime 之后的 datetime.strptime(...) 都能命中，别名也能被还原。
3. %z 豁免：若格式串（第 2 个参数）包含 %z，说明 strptime 本身已产出 aware 对象，直接返回（L112-L142）。实现上同时支持普通字符串字面量与 f-string（含隐式拼接的多个字面量片段，会逐个检查是否含 %z）。作为对照，测试 fixture DTZ007.py 中把 "%H:%M:%S%Z" 标注为 bad format——即只有 %z 被该规则视为 aware 指示符。
4. astimezone 短路：调用 followed_by_astimezone 检查链尾是否为 astimezone，是则放行（前述场景一）。
5. 反模式定位：find_antipattern（L153-L177）通过"祖父/父表达式"判断 strptime 调用处于何种外层结构：
   • 若外层不是 Call，或父节点不是 .replace 属性访问（包括把 .replace 当参数传递的裸方法引用等），报 NoTzArgumentPassed（场景三即由此命中）；
   • 若是 .replace(...) 调用：查 tzinfo 关键字参数——值为 None 时报 NonePassedToTzArgument；提供了非 None 的时区对象（如 tzinfo=timezone.utc）则放行；完全没传 tzinfo 则报 NoTzArgumentPassed。

DatetimeModuleAntipattern 这个枚举正是把上述两种反模式统一建模的载体（见 helpers.rs），DTZ007 的消息与修复建议均依据其变体分发。

正误对照速查表与推荐修复写法

写法	结果	判定依据
datetime.strptime(s, fmt)（格式串无 %z）	报警	naive 对象
datetime.strptime(s, fmt).replace(hour=1)（无 tzinfo）	报警	naive 对象
datetime.strptime(s, fmt).replace(tzinfo=None)	报警	显式置空 tzinfo
datetime.strptime(s, fmt).replace(tzinfo=timezone.utc)	放行	aware 对象
datetime.strptime(s, fmt).astimezone() / .astimezone(timezone.utc)	放行	aware 对象
datetime.strptime(s, "%Y-%m-%dT%H:%M:%S%z")（含 %z）	放行	strptime 直接产出 aware
.replace(microsecond=0).astimezone() 等多段链	放行	链尾 astimezone

规则的源码 docstring 给出了两条官方推荐的修复范式（规则定义文件）：

import datetime

# 原问题代码
datetime.datetime.strptime("2022/01/31", "%Y/%m/%d")

# 修复一：replace 补时区
datetime.datetime.strptime("2022/01/31", "%Y/%m/%d").replace(
    tzinfo=datetime.timezone.utc
)

# 修复二：astimezone 转换
datetime.datetime.strptime("2022/01/31", "%Y/%m/%d").astimezone(datetime.timezone.utc)

另有一个版本细节来自同一份源码文档：Python 3.11 及以后，datetime.timezone.utc 可以直接写成 datetime.UTC，代码更简洁。开发者可根据"解析出的时间戳应归属哪个时区"这一业务语义，在 replace(tzinfo=...)（直接把目标时区标注在 naive 结果上）与 astimezone(...)（把某个时刻转换到目标时区显示）之间做选择。

验证闭环：fixture、快照与 mdtest 三层测试

DTZ007 的规则行为在仓库中由三条不同层次的测试链路共同守护：

1. 传统 fixture 回归：crates/ruff_linter/resources/test/fixtures/flake8_datetimez/DTZ007.py 汇总了更全面的真实场景（如带 %Z 的格式串、无任何链式调用的裸 strptime、f-string 拼接 %z、replace(tzinfo=timezone.utc) 的正确写法等），其预期诊断固化在快照 call-datetime-strptime-without-zone_DTZ007.py.snap 中，任何行为变更都会使快照测试失败。
2. 文档即测试（mdtest）：本文所讲解的 call-datetime-strptime-without-zone.md 本身就属于一类"可执行的规则文档"——ruff_mdtest 集成测试会扫描 ../ruff_linter/resources/mdtest 下所有 .md 文件（tests/mdtest.rs），解析其中的 toml 配置与带 # error: 标注的 Python 代码块，逐条断言诊断是否按预期出现或缺席。
3. 解析器底座：mdtest 格式由 crates/mdtest 承载，其核心输出是一个 MarkdownTestSuite（把 Markdown 解析为一组 section + 内嵌 Python 文件 + 配置），规则名到错误码的映射最终落点之一是 规则选择器注册表。

因此，本文引用的三段规范代码既是"给人看的文档"，也是"给 CI 跑的测试"——文档中每一处 # error: [call-datetime-strptime-without-zone] 的注释，都是经过真实执行验证的行为契约。同一目录下的姊妹文档 datetime-min-max.md（对应 DTZ901 规则）采用完全相同的模式覆盖 datetime.min / datetime.max 与 tzinfo=None 的组合，可作为理解该文档风格的横向参考。

小结

Ruff 的 DTZ007（call-datetime-strptime-without-zone）通过在 AST 调用链层面判定"是否由不含 %z 的 strptime 产生 naive datetime 且未在链尾经 astimezone 或 replace(tzinfo=<真实时区>) 兜底"，帮助 Python 项目落地"始终使用 aware datetime"的时区安全规范。理解其三步豁免条件——格式串含 %z、链尾 astimezone、replace 携带非 None 的 tzinfo——就能在日常审查中快速判断代码是否会被该规则放行；而借助 lint.select = ["DTZ007"] 一行配置，即可将其纳入工程的门禁体系。对于想为其他规则补充此类"可执行文档"的贡献者，mdtest 模式（Markdown + toml 配置 + # error: 注释）也提供了一条文档、示例与断言三位一体的范例路径。