tzlocal：填补 Python 时区获取的底层缺口

Python 标准库里的 zoneinfo 和曾经的 pytz 都有一个明显的漏洞：你不知道自己在哪个时区。

除非提前查好 zoneinfo 名称，在 Linux 上这件事尤其麻烦，有时根本无从下手。tzlocal 就是专门解决这个问题的。

一个函数，搞定时区

tzlocal 的核心只有一个函数：get_localzone()。调用它，就能拿到一个包含本地时区信息的 tzinfo 对象。

from tzlocal import get_localzone
tz = get_localzone()
# zoneinfo.ZoneInfo(key='Europe/Warsaw')

拿到时区对象后，创建带时区的 datetime 就顺理成章了：

from datetime import datetime
dt = datetime(2015, 4, 10, 7, 22, tzinfo=tz)

配合 zoneinfo 做跨时区转换也很直接：

from zoneinfo import ZoneInfo
eastern = ZoneInfo('US/Eastern')
dt.astimezone(eastern)
# datetime.datetime(2015, 4, 10, 1, 22, tzinfo=zoneinfo.ZoneInfo(key='US/Eastern'))

如果只需要时区名称，4.0 版本新增了 get_localzone_name() 函数。不过要注意，在 Unix 下如果系统没有配置时区名称，这个函数会报错，而 get_localzone() 仍能正常工作。

兼容性做得扎实

tzlocal 支持 Windows 2000 及以上版本，以及任何带 /etc/localtime 或 /usr/local/etc/localtime 的 Unix 系统。

时区名称的查找路径覆盖了常见的几种配置方式：/etc/timezone、/var/db/zoneinfo、/etc/sysconfig/clock、/etc/conf.d/clock。如果 /etc/localtime 是一个符号链接，也能从链接路径中提取时区名称。

就算系统完全没有配置时区，tzlocal 也不会崩溃。它会返回一个名为 local 的时区对象，或者在不支持的情况下默认回退到 UTC。这个设计让它在 Docker 容器这种时区配置经常出问题的环境里也能平稳运行。

版本迭代路线清晰

tzlocal 的版本演进值得关注。3.0 版本从 pytz 迁移到了 zoneinfo 对象，API 发生了变更。4.0 版本通过 pytz_deprecation_shim 恢复了对 pytz 用户的部分兼容，同时新增了 get_localzone_name() 函数，并大幅提升了配置错误诊断信息的详细程度。

5.0 版本移除了 pytz_deprecation_shim，彻底转向 zoneinfo。如果还在用 pytz，需要留在 4.x 分支。作者承诺 4.x 分支仍会接受 bug 修复，不再添加新功能。

这个版本策略对依赖时区处理的项目来说足够清晰，不折腾。

适合谁用

如果你做的是需要处理历史时间的项目，比如跨时区的日程管理、全球用户的日志分析、金融交易时间戳转换，tzlocal 能省去手动查找和配置时区的麻烦。

如果只是需要把当前 UTC 时间转成本地时间，Python 标准库的 time 模块就够用了，不需要引入 tzlocal。这也是 README 里明确写出来的：tzlocal 不是为简单的 UTC 到本地时间转换设计的。

安装和调试

pip install tzlocal 一条命令搞定。遇到预期之外的结果，README 也提供了调试方法：

import logging
logging.basicConfig(level="DEBUG")
import tzlocal
tzlocal.get_localzone()

debug 日志会列出它找到了哪些配置文件、每个文件的内容是什么，帮助快速定位时区配置问题。

项目采用 MIT 协议开源，由 Lennart Regebro 维护，20 多位贡献者参与开发。

文件的内容是什么，帮助快速定位时区配置问题。

项目采用 MIT 协议开源，由 Lennart Regebro 维护，20 多位贡献者参与开发。