如何将Python datetime按指定秒级频率对齐到下一个完整时间点

错误原因 #

直接对Unix时间戳按频率取模的计算逻辑基于UTC时间零点，和本地时区的自然时间起始节点存在固定时差，因此得到的对齐结果会偏移。

通用实现代码 #

import datetime

def align_to_next_freq(dt: datetime.datetime, freq_sec: int) -> datetime.datetime:
    # 若无指定时区，默认按本地时区处理
    if dt.tzinfo is None:
        dt = dt.astimezone()
    # 转换为本地时区对应总秒数后计算对齐偏移
    total_seconds = dt.timestamp() + dt.utcoffset().total_seconds()
    delta = freq_sec - (total_seconds % freq_sec)
    # 当前时间已是对齐节点时直接返回
    if delta == freq_sec:
        return dt
    return dt + datetime.timedelta(seconds=delta)

# 示例测试
freq = 86400
starttime = datetime.datetime.fromisoformat('2018-02-12 17:30:24')
result = align_to_next_freq(starttime, freq)
# 如需输出无时区信息的时间，可添加 .replace(tzinfo=None)
print(result.replace(tzinfo=None))
# 输出：2018-02-13 00:00:00

方案说明 #

• 支持任意秒级频率的对齐需求：3小时对应freq_sec=10800、2周对应freq_sec=1209600均可直接使用，无需额外适配
• 自动适配本地时区的时间节点，无需手动计算时区偏移量
• 若输入时间本身正好是对齐节点，会直接返回原时间
• 如果需要对齐UTC时间的节点，只需将dt = dt.astimezone()替换为dt = dt.replace(tzinfo=datetime.timezone.utc)即可
• 如果需要按周对齐且指定周起始日（比如周一），可在计算total_seconds后减去对应基准偏移量再取模，比如周一对应减去4*86400（1970-01-01为周四）

内容的提问来源于stack exchange，提问作者Nomenator