datetime fold 怎样处理重复时间

当时钟回拨导致同一本地时间出现两次时，datetime.fold 用 0 和 1 区分较早和较晚的两个时刻。配合 ZoneInfo，先确认输入确实存在歧义，再选择 fold，并把选定时间转换为 UTC 保存。单独写一个“02:30”或默认使用 fold=0，都不能替来源方说明他实际指哪一次。

本文用历史的柏林本地时间 2023-10-29 02:30 构造原创示例。代码未在本机执行，文中的候选值是按时区规则解释的预期，不是终端实测结果。

官方入口：https://docs.python.org/3/library/zoneinfo.html。fold 定义：https://peps.python.org/pep-0495/。日期比较规则：https://docs.python.org/3/library/datetime.html。

数据来源：本地钟表时间缺了什么

一条预约记录通常来自日期字段、时间字段和地区选择。本地钟表值 wall 只是表面读数；zone_key 才说明采用哪个地区的时区规则。即使同时提供这两项，回拨重叠区间内也可能对应两个候选时刻。

fold 不是“是否夏令时”的通用开关。它表达同一重复时间的先后，不能假设所有回拨都由夏令时引起，也不能把变化幅度写死为一小时。业务界面适合展示两个候选各自的 UTC 偏移和说明，让用户选定，而不是直接把原始字段覆盖掉。

识别歧义：枚举两个 fold 候选

以下函数把 fold=0 和 fold=1 分别作为候选，经 UTC 往返检查钟表字段是否仍然成立，再按 UTC 去重。这是应用层的一种处理办法，不是 datetime 构造函数自动进行的输入校验。普通时间得到一个候选，回拨重复时间得到两个，跳时缺口得到零个。

from datetime import datetime, timezone
from zoneinfo import ZoneInfo


def local_candidates(wall, zone_key):
    # 本函数只接受未绑定时区的本地钟表输入。
    if wall.tzinfo is not None:
        raise ValueError("请传入不带 tzinfo 的本地时间")
    zone = ZoneInfo(zone_key)
    by_utc = {}
    for fold in (0, 1):
        local = wall.replace(tzinfo=zone, fold=fold)
        instant = local.astimezone(timezone.utc)
        restored = instant.astimezone(zone)
        # UTC 往返后必须还原原始钟表字段，排除不存在的时间。
        if restored.replace(tzinfo=None, fold=0) == wall.replace(fold=0):
            # 用 UTC 键去重：普通时刻的两个 fold 不应算两个候选。
            by_utc[instant] = restored
    return [(instant, by_utc[instant]) for instant in sorted(by_utc)]


wall = datetime(2023, 10, 29, 2, 30)
zone_key = "Europe/Berlin"
options = local_candidates(wall, zone_key)
for instant, local in options:
    print("本地：", local.isoformat(), "fold：", local.fold)
    print("UTC：", instant.isoformat())
# 这里仅展示候选，业务必须让来源方确认需要哪一个时刻。

函数保留 UTC instant 和回转后的 local：前者适合确定时刻，后者适合展示偏移及 fold。不能把两个带同一 tzinfo 的本地 datetime 直接作为这里的去重键，否则可能忽略想要保留的 fold 区别。

存储模型：保存确定时刻与用户选择

对于已经发生或已经确认的单次事件，可把 instant_utc 作为确定时刻，同时保存 zone_key、local_input、selected_fold 和 selected_offset 作为来源上下文。这个模型是本文建议，不是 Python 强制的数据库结构。不要仅保存本地时间加 fold，却丢掉地区规则。

# 接在前面的候选识别代码后；choice 来自用户明确确认。
choice = 1
if len(options) != 2:
    raise ValueError("当前输入并不是需要二选一的重复时间")
if choice not in (0, 1):
    raise ValueError("候选编号只能是 0 或 1")
instant, selected = options[choice]
record = {
    "instant_utc": instant.isoformat(),
    "zone_key": zone_key,
    "local_input": wall.isoformat(),
    "selected_fold": selected.fold,
    "selected_offset": str(selected.utcoffset()),
}
# 后续排序或范围筛选使用 instant_utc 的统一时刻语义。
print(record)

choice=1 只是教学示例，表示用户已选择按 UTC 排序后的较晚候选；实际系统不能把这一行当作自动决策。字段 selected_fold 来自 selected，而不是凭候选索引猜测。若调用方提供的是已确定 UTC 时刻，应直接转换展示，不必再要求用户选 fold。

查询路径：按 UTC 比较，按时区展示

在具备该历史时区数据的环境里，本例两个候选分别关联 +02:00 和 +01:00 的偏移，UTC 时刻对应 00:30 与 01:30。它们的本地钟表字段相同，但代表不同瞬间。这里只解释这个历史案例，不把差值推广到所有时区回拨。

比较、去重及计算真实经过时长时，先转换到 UTC。datetime 对两个 tzinfo 为同一对象的 aware 值进行某些比较和相减时，会忽略 fold 差异；因此用原始 local 对象做“是否同一瞬间”的判断可能出乎预期。

展示时用已保存的 UTC 时刻调用 astimezone(ZoneInfo(zone_key))。从确定时刻转换到本地区域，ZoneInfo 会按规则给出相应 fold。导出接口若只给不带偏移的日期字符串，消费者将再次丢失区分两个时刻的线索。

异常处理：区分重复时间与不存在时间

给不存在的时间设置 fold=1，不会把它变成有效时间。datetime 允许构造某些无效组合，因此需要业务自己的确认规则。ZoneInfo 使用系统 IANA 数据，缺失时可使用第一方 tzdata 包；跨环境部署应显式管理可用的数据源，不把资料缺失误报成用户填错日期。

清理策略与常见疑问

事件归档和删除应按业务记录处理。不要用本地钟表文本作为唯一标识去“清理重复数据”，否则回拨后的两次真实事件可能被误合并。保留多久的原始输入和选择上下文，由业务审计与数据保留约定决定。

fold=1 总代表有效的第二次吗？

只有输入确实落在重复区间时，这个解释才有意义。普通时间设置 fold=1 并不意味着创造了第二个时刻，不能仅靠属性值判断输入存在歧义。

replace(tzinfo=...) 和 astimezone 有什么不同？

本例的 replace 用于给未带时区的钟表字段绑定解释；astimezone 则在确定时刻语义下转换地区表示。若原值已经代表某个时刻，直接 replace 换地区会改变解释，应使用转换方法。

保存 ISO 字符串就能保存 fold 吗？

带偏移的字符串可以表达偏移与时刻，但普通 ISO 日期时间格式不单独编码 Python 的 fold 和地区键。需要保留来源选择时，应把这些上下文单独保存。

未来每天重复的预约也只存一个 UTC 吗？

不应直接套用单次事件模型。周期预约还要保留本地规则和地区，并定义未来遇到重复或缺失时间时的选择策略。本文只处理一次输入对应哪个确定时刻，不延伸为周期调度实现。