zoneinfo — IANA 时区支持¶
3.9 版本新增。
源代码: Lib/zoneinfo
zoneinfo 模块提供了一个具体的时区实现，用于支持 IANA 时区数据库，该数据库最初在 PEP 615 中指定。默认情况下，zoneinfo 使用系统的时区数据（如果可用）；如果系统时区数据不可用，则该库将回退到使用 PyPI 上提供的第一方 tzdata 包。
另请参阅
可用性: 不适用于 WASI。
此模块在 WebAssembly 上无法工作或不可用。有关更多信息，请参阅 WebAssembly 平台。
使用 ZoneInfo¶
ZoneInfo 是 datetime.tzinfo 抽象基类的具体实现，旨在附加到 tzinfo，可以通过构造函数、datetime.replace 方法或 datetime.astimezone。
>>> from zoneinfo import ZoneInfo
>>> from datetime import datetime, timedelta
>>> dt = datetime(2020, 10, 31, 12, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(dt)
2020-10-31 12:00:00-07:00
>>> dt.tzname()
'PDT'
以这种方式构造的日期时间与日期时间算术兼容，并且无需进一步干预即可处理夏令时转换。
>>> dt_add = dt + timedelta(days=1)
>>> print(dt_add)
2020-11-01 12:00:00-08:00
>>> dt_add.tzname()
'PST'
这些时区还支持 PEP 495 中引入的 fold 属性。在导致时间模糊的偏移量转换期间（例如，从夏令时到标准时间的转换），当 fold=0 时，使用转换之前的偏移量，当 fold=1 时，使用转换之后的偏移量，例如：
>>> dt = datetime(2020, 11, 1, 1, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(dt)
2020-11-01 01:00:00-07:00
>>> print(dt.replace(fold=1))
2020-11-01 01:00:00-08:00
从另一个时区转换时，fold 将设置为正确的值
>>> from datetime import timezone
>>> LOS_ANGELES = ZoneInfo("America/Los_Angeles")
>>> dt_utc = datetime(2020, 11, 1, 8, tzinfo=timezone.utc)
>>> # Before the PDT -> PST transition
>>> print(dt_utc.astimezone(LOS_ANGELES))
2020-11-01 01:00:00-07:00
>>> # After the PDT -> PST transition
>>> print((dt_utc + timedelta(hours=1)).astimezone(LOS_ANGELES))
2020-11-01 01:00:00-08:00
数据源¶
zoneinfo 模块不直接提供时区数据，而是从系统时区数据库或第一方 PyPI 包 tzdata（如果可用）中提取时区信息。某些系统（包括著名的 Windows 系统）没有可用的 IANA 数据库，因此对于需要时区数据且以跨平台兼容性为目标的项目，建议声明对 tzdata 的依赖。如果系统数据和 tzdata 都不可用，则对 ZoneInfo 的所有调用都会引发 ZoneInfoNotFoundError。
配置数据源¶
当调用 ZoneInfo(key) 时，构造函数首先在 TZPATH 中指定的目录中搜索与 key 匹配的文件，如果失败，则在 tzdata 包中查找匹配项。此行为可以通过三种方式配置：
编译时配置¶
默认的 TZPATH 包括时区数据库的几个常见部署位置（在 Windows 上除外，因为 Windows 没有时区数据的“众所周知”的位置）。在 POSIX 系统上，下游分发者和从源代码构建 Python 的人员如果知道其系统时区数据的部署位置，可以通过指定编译时选项 TZPATH（或更有可能使用 configure 标志 --with-tzpath）来更改默认时区路径，该选项应是以 os.pathsep 分隔的字符串。
在所有平台上，配置的值都可用作 sysconfig.get_config_var() 中的 TZPATH 键。
环境配置¶
当初始化 TZPATH 时（在导入时或在调用 reset_tzpath() 时不带参数），zoneinfo 模块将使用环境变量 PYTHONTZPATH（如果存在）来设置搜索路径。
- PYTHONTZPATH¶
这是一个以
os.pathsep分隔的字符串，其中包含要使用的时区搜索路径。它必须仅由绝对路径而不是相对路径组成。PYTHONTZPATH中指定的相对组件将不会被使用，但否则指定相对路径时的行为是实现定义的；CPython 将引发InvalidTZPathWarning，但其他实现可以自由地忽略错误的组件或引发异常。
要将系统设置为忽略系统数据并改用 tzdata 包，请设置 PYTHONTZPATH=""。
运行时配置¶
TZ 搜索路径也可以在运行时使用 reset_tzpath() 函数进行配置。这通常不是一个明智的操作，尽管在需要使用特定时区路径（或需要禁用对系统时区的访问）的测试函数中使用它是合理的。
ZoneInfo 类¶
- class zoneinfo.ZoneInfo(key)¶
一个具体的
datetime.tzinfo子类，表示由字符串key指定的 IANA 时区。对主构造函数的调用将始终返回比较相同的对象；换句话说，除非通过ZoneInfo.clear_cache()使缓存失效，否则对于key的所有值，以下断言始终为真a = ZoneInfo(key) b = ZoneInfo(key) assert a is b
key必须采用相对、规范化的 POSIX 路径形式，且不包含向上级引用的路径。如果传递的键不符合要求，则构造函数将引发ValueError。如果找不到与
key匹配的文件，构造函数将引发ZoneInfoNotFoundError。
ZoneInfo 类有两个备用构造函数
- classmethod ZoneInfo.from_file(fobj, /, key=None)¶
从返回字节的文件类对象（例如，以二进制模式打开的文件或
io.BytesIO对象）构造一个ZoneInfo对象。与主构造函数不同，此函数始终构造一个新对象。key参数设置区域的名称，用于__str__()和__repr__()。通过此构造函数创建的对象无法被 pickle 序列化（请参阅 pickle 序列化）。
- classmethod ZoneInfo.no_cache(key)¶
一个绕过构造函数缓存的备用构造函数。它与主构造函数相同，但在每次调用时返回一个新对象。这最有可能用于测试或演示目的，但也可用于创建具有不同缓存失效策略的系统。
通过此构造函数创建的对象在反序列化时也将绕过反序列化进程的缓存。
注意
使用此构造函数可能会以令人惊讶的方式更改日期时间的语义，仅在您知道需要使用时才使用它。
以下类方法也可用
- classmethod ZoneInfo.clear_cache(*, only_keys=None)¶
一种使
ZoneInfo类上的缓存失效的方法。如果未传递任何参数，则所有缓存都将失效，并且对每个键的主构造函数的下一次调用将返回一个新实例。如果将键名称的可迭代对象传递给
only_keys参数，则只会从缓存中删除指定的键。传递给only_keys但未在缓存中找到的键将被忽略。警告
调用此函数可能会以令人惊讶的方式更改使用
ZoneInfo的日期时间的语义；这会修改模块状态，因此可能会产生广泛的影响。仅在您知道需要使用时才使用它。
该类具有一个属性
- ZoneInfo.key¶
这是一个只读的 属性，返回传递给构造函数的
key的值，该值应该是 IANA 时区数据库中的查找键（例如，America/New_York、Europe/Paris或Asia/Tokyo）。对于从文件构造且未指定
key参数的区域，此值将设置为None。注意
尽管将这些值暴露给最终用户是一种常见的做法，但这些值旨在作为表示相关区域的主键，而不一定是面向用户的元素。可以使用诸如 CLDR（Unicode 通用区域设置数据存储库）之类的项目从这些键中获取更友好的字符串。
字符串表示形式¶
在 ZoneInfo 对象上调用 str 时返回的字符串表示形式默认使用 ZoneInfo.key 属性（请参阅属性文档中的使用说明）
>>> zone = ZoneInfo("Pacific/Kwajalein")
>>> str(zone)
'Pacific/Kwajalein'
>>> dt = datetime(2020, 4, 1, 3, 15, tzinfo=zone)
>>> f"{dt.isoformat()} [{dt.tzinfo}]"
'2020-04-01T03:15:00+12:00 [Pacific/Kwajalein]'
对于从文件构造且未指定 key 参数的对象，str 将回退到调用 repr()。ZoneInfo 的 repr 是实现定义的，并且在版本之间不一定稳定，但保证它不是有效的 ZoneInfo 键。
Pickle 序列化¶
ZoneInfo 对象不是序列化所有转换数据，而是按键序列化，并且从文件构造的 ZoneInfo 对象（即使指定了 key 的值）也无法 pickle 序列化。
ZoneInfo 文件的行为取决于其构造方式
ZoneInfo(key)：使用主构造函数构造时，ZoneInfo对象按键序列化，并且在反序列化时，反序列化进程使用主构造函数，因此可以预期这些对象与对同一时区的其他引用相同。例如，如果europe_berlin_pkl是一个字符串，其中包含从ZoneInfo("Europe/Berlin")构造的 pickle，则可以预期以下行为>>> a = ZoneInfo("Europe/Berlin") >>> b = pickle.loads(europe_berlin_pkl) >>> a is b True
ZoneInfo.no_cache(key)：从绕过缓存的构造函数构造时，ZoneInfo对象也按键序列化，但是当反序列化时，反序列化进程使用绕过缓存的构造函数。如果europe_berlin_pkl_nc是一个字符串，其中包含从ZoneInfo.no_cache("Europe/Berlin")构造的 pickle，则可以预期以下行为>>> a = ZoneInfo("Europe/Berlin") >>> b = pickle.loads(europe_berlin_pkl_nc) >>> a is b False
ZoneInfo.from_file(fobj, /, key=None)：从文件构造时，ZoneInfo对象在进行 pickle 时引发异常。如果最终用户想要 pickle 从文件构造的ZoneInfo，建议他们使用包装器类型或自定义序列化函数：按键序列化或存储文件对象的内容并序列化该内容。
这种序列化方法要求所需的键的时区数据在序列化和反序列化端都可用，类似于类和函数的引用在序列化和反序列化环境中都存在的方式。这也意味着，当在具有不同版本时区数据的环境中反序列化 pickle 的 ZoneInfo 时，不能保证结果的一致性。
函数¶
- zoneinfo.available_timezones()¶
获取一个集合，其中包含时区路径上任何位置可用的 IANA 时区的所有有效键。每次调用该函数时都会重新计算此值。
此函数仅包括规范的区域名称，不包括
posix/和right/目录下的“特殊”区域或posixrules区域。注意
此函数可能会打开大量文件，因为确定时区路径上的文件是否为有效的时区的最佳方法是读取开头的“魔术字符串”。
注意
这些值并非设计为向最终用户公开；对于面向用户的元素，应用程序应使用诸如 CLDR (Unicode 通用区域设置数据存储库) 之类的东西来获取更用户友好的字符串。另请参阅关于
ZoneInfo.key的注意事项。
- zoneinfo.reset_tzpath(to=None)¶
设置或重置模块的时区搜索路径 (
TZPATH)。当不带参数调用时，TZPATH将设置为默认值。调用
reset_tzpath不会使ZoneInfo缓存失效，因此，只有在缓存未命中时，对主ZoneInfo构造函数的调用才会使用新的TZPATH。to参数必须是字符串或os.PathLike的序列，而不是字符串，所有这些都必须是绝对路径。如果传递了绝对路径以外的内容，将引发ValueError。
全局变量¶
- zoneinfo.TZPATH¶
一个表示时区搜索路径的只读序列——当从键构造
ZoneInfo时，该键会与TZPATH中的每个条目连接，并使用找到的第一个文件。TZPATH可能只包含绝对路径，永远不包含相对路径，无论它是如何配置的。zoneinfo.TZPATH指向的对象可能会响应对reset_tzpath()的调用而发生更改，因此建议使用zoneinfo.TZPATH，而不是从zoneinfo导入TZPATH或将一个长期存在的变量分配给zoneinfo.TZPATH。有关配置时区搜索路径的更多信息，请参阅 配置数据源。
异常和警告¶
- exception zoneinfo.InvalidTZPathWarning¶
当
PYTHONTZPATH包含将被过滤掉的无效组件（例如相对路径）时引发。