Python 库手册：zoneinfo 时区处理模块

zoneinfo 是 Python 3.9 引入的标准库模块，用于为 datetime 对象提供真实的时区信息支持。它是对第三方库 pytz 的官方替代，实现了对 IANA 时区数据库（tzdata）的内置访问，使得 Python 可以更准确地处理全球时间差异与夏令时变更。

常见应用场景：

（1）显示本地或全球用户的当前时间。

（2）会议日程系统中支持跨时区转换。

（3）日志与数据记录统一使用 UTC，展示时转换为用户时区。

（4）自动处理夏令时的跳变与偏移逻辑。

◆ ◆ ◆

核心概念

1、zoneinfo 是模块名，内部主要提供一个类：ZoneInfo。

ZoneInfo 类用于构建具体的时区对象。

2、zoneinfo 模块基于 IANA tz 数据库，比如：

"Asia/Shanghai"、"America/New_York"。

3、可与 datetime.datetime 配合使用，形成可感知时区的时间对象。

4、Python 3.11+ 提供 available_timezones() ，可列出所有支持的时区。

5、若加载失败会抛出 ZoneInfoNotFoundError。

◆ ◆ ◆

应用举例

例 1：创建指定时区的时间对象

from datetime import datetime
from zoneinfo import ZoneInfo

dt = datetime(2025, 7, 2, 15, 30, tzinfo=ZoneInfo("Asia/Shanghai"))
print(dt)  # 输出：2025-07-02 15:30:00+08:00

提示：须事先安装 tzdata 包。

例 2：UTC 时间转换为纽约时间

from datetime import datetime
from zoneinfo import ZoneInfo

utc_time = datetime(2025, 7, 2, 7, 30, tzinfo=ZoneInfo("UTC"))
ny_time = utc_time.astimezone(ZoneInfo("America/New_York"))
print(ny_time)  # 输出：2025-07-02 03:30:00-04:00

例 3：处理夏令时切换

from datetime import datetime, timedelta
from zoneinfo import ZoneInfo
before = datetime(2025, 3, 9, 1, 30, tzinfo=ZoneInfo("America/New_York"))
after = before + timedelta(hours=1)

print(before)  # 2025-03-09 01:30:00-05:00
print(after)   # 2025-03-09 03:30:00-04:00（夏令时跳变）

◆ ◆ ◆

常用函数速览

zoneinfo.ZoneInfo(key)

创建一个对应 IANA 时区的时区对象，用于赋予 datetime 对象 tzinfo。

参数：

key：字符串，IANA 时区名称，如 "Asia/Tokyo"

返回：ZoneInfo 对象

异常：若指定时区无效，会抛出 ZoneInfoNotFoundError

zoneinfo.available_timezones()

（Python 3.11+）获取当前系统支持的全部时区名称集合。

参数：无

返回：frozenset 字符串集合，例如 {"Asia/Shanghai", "Europe/Paris", ...}

zoneinfo.ZoneInfoNotFoundError

创建 ZoneInfo 时，如果指定时区名称末在当前 tzdata 中找到，会抛出该异常。

可用于异常处理或提供时区回退策略，如回退到 UTC。

◆ ◆ ◆

使用建议

1、推荐所有系统内部统一使用 UTC 存储时间，展示时才转换为用户时区。

2、zoneinfo.ZoneInfo 与 datetime.now() 或 datetime.utcnow() 配合使用可精确控制本地或全球时间。

3、若出现时区不可用错误，可安装 tzdata 包。

pip install tzdata

4、与 dateutil，pytz 的比较中，zoneinfo 是更现代、原生、推荐的方案。

5、典型 IANA 时区名称示例

“点赞有美意，赞赏是鼓励”