Python 教程 / 用 datetime 与 zoneinfo 处理日期和时区

只表示日历日期时使用 date;需要表示时刻和时区时,使用 datetime 配合 zoneinfo。必须区分带时区信息的 aware 值与缺乏这种解释的 naive 值,并明确存储和显示各采用什么规则,不能仅凭相同钟表数字判断是同一时刻。

区分日期、时间间隔与时刻

date 表示年月日,datetime 表示日期和时间,timedelta 表示时间间隔。naive datetime 无法单独确定它指 UTC 还是某个本地时间;aware 值包含可用的时区偏移信息。严格判断还涉及 utcoffset() 是否返回 None,不是只看对象有没有 tzinfo 属性。

用户输入可按约定用 date.fromisoformat 解析,非法日期会抛出 ValueError。增加 30 天与“下一个日历月的同一天”不是同一要求,尤其在月末。日期、偏移和运算规则见Python 官方 datetime 文档。

zoneinfo 使用 IANA(Internet Assigned Numbers Authority)时区数据库中的区域名称。若环境没有系统数据,也没有 tzdata 包,Asia/Seoul 等区域查找会失败。在所选项目虚拟环境中按需要执行 python -m pip install tzdata,不要因为示例缺数据就改动操作系统时区。跨平台项目应把所需依赖记录下来,说明见Python 官方 zoneinfo 数据来源。

将 UTC 时刻转换为首尔显示

将完整代码以 UTF-8 保存为 dates.py,在项目环境执行 python dates.py。若已核对的命令为 python3,则相应使用 python3 dates.py。先按上节准备时区数据:

from datetime import date, datetime, timedelta, timezone
from zoneinfo import ZoneInfo

day = date.fromisoformat("2026-10-17")
print(day + timedelta(days=7))
utc = datetime(2026, 10, 17, 0, 0, tzinfo=timezone.utc)
seoul = utc.astimezone(ZoneInfo("Asia/Seoul"))
print(utc.isoformat())
print(seoul.isoformat())

预期输出:

2026-10-24
2026-10-17T00:00:00+00:00
2026-10-17T09:00:00+09:00

第一行在 2026-10-17 的基础上增加七个日历日。后两行描述同一个时刻:UTC 00:00 在所用首尔时区规则下显示为 09:00,偏移为 +09:00。astimezone 改变显示方式,保持表示的时刻;原 utc 对象也没有被原地修改。

比较转换与只更换时区解释

第二份完整代码另存为 zones.py,执行 python zones.py,保留前一份程序:

from datetime import datetime, timezone
from zoneinfo import ZoneInfo
utc = datetime(2026, 10, 17, 0, 0, tzinfo=timezone.utc)
print(utc.astimezone(ZoneInfo("Asia/Seoul")).isoformat())
print(utc.replace(tzinfo=ZoneInfo("Asia/Seoul")).isoformat())
try:
    print(datetime(2026, 10, 17) - utc)
except TypeError:
    print("naive and aware cannot be subtracted")

预期输出:

2026-10-17T09:00:00+09:00
2026-10-17T00:00:00+09:00
naive and aware cannot be subtracted

第二行用 replace(tzinfo=...) 保留 00:00 的钟表字段,只改它采用的时区解释,因此与第一行并非同一时刻。这可用于你确实已知某组 naive 钟表字段属于哪个时区的场景,但不能替代一般时区转换。

最后的减法一边是 naive,一边是 aware,所以被捕获为 TypeError。英语提示表示两者不能直接相减。若来源时区未知,不应为了消除错误就随意贴上 UTC;先明确数据契约,再比较时刻。

区域规则可能随政策和数据库更新而变化。zoneinfo 从系统数据库或官方维护的 tzdata 包读取规则,应用部署时要管理这份数据。不要将本例某个日期的 +09:00 推广为所有区域、所有历史与未来日期都固定偏移。

确定保存规则并检查日期边界

  1. 在 dates.py 中仅把 UTC 构造时的小时从 0 改为 23。首尔显示应变为 2026-10-18T08:00:00+09:00,即第二天早上;恢复 0 再核对原结果。
  2. 把 date.fromisoformat 的输入单独改成 2026-02-30,应抛出 ValueError,因为该日历日期不存在;恢复 2026-10-17。
  3. 保留 zones.py,比较 astimezone 与 replace 的结果,将两者再转换回 UTC,检查前者保留原时刻、后者不保留。不要只比较钟表上的小时。

交易发生时刻可以按一致的 UTC 或带偏移格式保存,再按用户区域显示;若业务只关心“支出日期”,保留日期本身通常比任意添上午夜时刻更明确。保存为 JSON 时还要明确字符串格式,不能假设 datetime 对象会自动序列化,相关区别见JSON 数据转换。

日期筛选与时刻筛选也应采用同一契约:先确定用户说的某一天属于哪个区域,再确定查询范围。遇到夏令时变化的区域,还需核对当地时间是否重复或不存在,不能把本例普通首尔日期的结果视作完整的所有时区调度方案。