Python zoneinfo 缓存什么时候需要清除

Python 的 zoneinfo 缓存通常不需要手动清除。用 ZoneInfo("Europe/Berlin") 创建时，主构造器会按时区 key 复用实例；只有在测试需要隔离对象、运行时切换时区数据路径，或确实要让后续构造重新读取数据时，才考虑 ZoneInfo.clear_cache()。清理缓存不会改写已经保存的业务规则，却可能改变后续对象的身份和已有 datetime 的比较语义。

官方文档：https://docs.python.org/3/library/zoneinfo.html

先看懂 ZoneInfo 的缓存对象身份

这里最容易混淆的是“时区数据相同”和“对象就是同一个”。主构造器在缓存未失效时保证相同 key 返回可用 is 判断的同一实例。它减少了重复解析，也让依赖时区对象身份的代码有稳定行为。

from zoneinfo import ZoneInfo

# 同一个 key 默认命中主构造器缓存，身份相同是设计行为
berlin_a = ZoneInfo("Europe/Berlin")
berlin_b = ZoneInfo("Europe/Berlin")
assert berlin_a is berlin_b

# 不要用“必须是新对象”来判断时区规则是否更新
print(berlin_a.key)

因此，如果代码只是反复把字符串转换成 ZoneInfo，不需要在每次请求后清缓存。缓存命中本身也不是时区偏移错误的证据；遇到夏令时边界，应先检查本地时间是否明确、是否需要 fold，再考虑缓存。

哪些场景才值得清理缓存

比较合理的场景有三类：测试先构造对象、再切换 PYTHONTZPATH 或调用 reset_tzpath()；测试需要验证两个阶段使用不同的时区数据；应用明确采用“替换时区数据后让新构造器重新读取”的策略。生产进程里临时清缓存来“修复时间不准”，通常会把问题扩大。

reset_tzpath() 只改变搜索路径，不负责让既有缓存失效。若确实要让某个 key 重新构造，可以把影响范围缩到该 key：

from zoneinfo import ZoneInfo, reset_tzpath

# 测试中先切换到准备好的绝对路径；真实路径应由测试夹具提供
reset_tzpath(["/srv/test-tzdata"])

# 只让一个 key 的后续构造重新读取，避免影响无关时区
ZoneInfo.clear_cache(only_keys={"Europe/Berlin"})
fresh = ZoneInfo("Europe/Berlin")

# 旧对象仍然存在；清理不会回溯改写它的引用
print(fresh.key)

全量 ZoneInfo.clear_cache() 应当只在测试夹具或明确的进程级切换点使用。它会让之后的主构造器返回新实例，而旧的 datetime 仍持有旧的 tzinfo。如果同一批数据同时混用新旧对象，排查成本会明显上升。

clear_cache、only_keys 与 no_cache 怎么选

no_cache() 更适合一次性测试或演示，不是生产环境的“强制刷新按钮”。官方文档明确提醒，绕过缓存和清理缓存都可能改变 datetime 的语义；如果只是想测试逻辑分支，优先在测试中隔离构造器，而不是让整个常驻进程进入混合状态。

把清理动作放进可回滚的测试边界

建议把路径切换、缓存清理、对象断言和测试结束后的恢复写在同一个 fixture 或上下文中，并在日志中记录 key 与动作范围。不要只写一句“刷新时区缓存”，否则后续读代码的人无法判断是换数据、隔离身份，还是试图掩盖夏令时转换问题。

from zoneinfo import ZoneInfo

def assert_cache_boundary(key: str) -> None:
    # 用 identity 明确测试目标，而不是把对象相等误当成数据版本检查
    before = ZoneInfo(key)
    ZoneInfo.clear_cache(only_keys={key})
    after = ZoneInfo(key)
    assert before is not after
    assert before.key == after.key

assert_cache_boundary("Europe/Berlin")

这个断言只证明缓存边界发生了变化，不证明两份时区数据库内容不同。若目标是验证规则更新，还要在测试夹具中固定数据来源，并用一个已知的转换样例比较偏移；不能把 is not 当成时区数据版本号。

常见问题

调用 reset_tzpath 后为什么还是旧对象？

因为它不会自动失效 ZoneInfo 缓存。需要在受控测试场景下按 key 清理，或者让新进程加载新的路径。

clear_cache 会修改已经创建的 datetime 吗？

不会回溯替换对象内部引用，但后续构造可能得到新的 tzinfo 实例。新旧对象混用时，身份比较和序列化行为都要重新检查。

生产环境应该定时清理吗？

通常不应该。把时区数据升级设计成部署或进程重启边界，比在请求处理中全量清理更容易观察、回滚和验证。