time.mktime在Debian Docker镜像中触发OverflowError问题排查

环境与问题现象 #

使用python:3.9.7 Docker镜像、pytz==2021.3环境时，调用time.mktime处理带时区感知的datetime对象会触发OverflowError，但本地主机运行相同代码正常。将容器系统时间改为2024年3月7日时，异常消失。

示例代码：

import datetime
import time
import pytz

tz = 'Canada/Eastern'

utc_time = datetime.datetime.now(tz=pytz.utc)

tz = pytz.timezone(tz)
tz_aware = datetime.datetime.now(tz=tz)

utc_ts = time.mktime(utc_time.timetuple()) # 无异常

ts = time.mktime(tz_aware.timetuple()) # 触发异常

异常信息：

Traceback (most recent call last):
  File "/home/toy_example.py", line 15, in <module>
    time.mktime(tz_aware.timetuple())
OverflowError: mktime argument out of range

原因解析 #

• time.mktime的设计限制：该函数仅能处理系统本地时区下的有效时间，要求传入的timetuple必须是本地时区的时间。Docker容器默认时区为UTC，当你将Canada/Eastern时区的datetime转成timetuple后，time.mktime会错误地将其当作UTC时区的时间解析，若该时间在UTC时区中属于无效值（比如夏令时切换导致的重复/不存在时间点），就会触发溢出异常。
• 夏令时切换的影响：Canada/Eastern时区的夏令时切换期（通常为3月第二个周日至11月第一个周日）会出现时间歧义：比如切换时会有1小时的重复时间，或跳过1小时。当代码运行在切换临界期内时，生成的timetuple包含time.mktime无法识别的异常时间值，从而报错。2024年3月7日不在夏令时切换窗口内（当年切换日为3月10日），此时时区转换无歧义，因此异常消失。
• pytz版本的细节问题：pytz==2021.3的时区数据处理逻辑在夏令时切换临界期，生成的timetuple可能包含超出time.mktime处理范围的字段值，进一步加剧了异常触发的概率。

正确处理方式 #

避免使用time.mktime处理带时区感知的datetime，直接使用datetime对象的timestamp()方法生成UTC时间戳，该方法不依赖系统时区，且能正确处理夏令时：

ts = tz_aware.timestamp()

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