构造函数

zoneinfo.ZoneInfo 类的初始设计有几个构造函数。

ZoneInfo(key: str)

主构造函数接受一个参数 key，它是一个字符串，表示系统时区数据库中时区文件的名称（例如 "America/New_York", "Europe/London"），并返回从搜索路径上第一个匹配数据源构建的 ZoneInfo 对象（有关更多详细信息，请参阅数据源部分）。所有时区信息必须在构造时从数据源（通常是 TZif 文件）急切读取，并且在对象的生命周期内不得更改（此限制适用于所有 ZoneInfo 构造函数）。

如果在搜索路径上找不到匹配的文件（无论是由于系统未提供时区数据还是由于键无效），构造函数将引发 zoneinfo.ZoneInfoNotFoundError，它将是 KeyError 的子类。

此构造函数做出的一项不寻常的保证是，使用相同参数的调用必须返回 相同 的对象。具体来说，对于 key 的所有值，以下断言必须始终有效 [b]

a = ZoneInfo(key)
b = ZoneInfo(key)
assert a is b

其原因在于，datetime 操作（例如比较、算术）的语义取决于所涉及的 datetime 是否表示相同或不同的时区；两个 datetime 仅在 dt1.tzinfo is dt2.tzinfo 时才处于同一时区。[1] 除了避免不必要地创建 ZoneInfo 对象带来的适度性能优势外，提供此保证应能最大程度地减少最终用户的意外行为。

dateutil.tz.gettz 自 2.7.0 版（2018 年 3 月发布）以来提供了类似的保证。[16]

ZoneInfo.no_cache(key: str)

这是一个替代构造函数，它绕过了构造函数的缓存。它与主构造函数相同，但每次调用都会返回一个新对象。这可能主要用于测试目的，或者故意在具有相同名义时区的 datetime 之间引起“不同时区”语义。

即使通过此方法构造的对象是缓存未命中，也不得将其输入到缓存中；换句话说，以下断言应始终为真

>>> a = ZoneInfo.no_cache(key)
>>> b = ZoneInfo(key)
>>> a is not b

ZoneInfo.from_file(fobj: IO[bytes], /, key: str = None)

这是一个替代构造函数，允许从任何 TZif 字节流构造 ZoneInfo 对象。此构造函数接受一个可选参数 key，该参数设置时区的名称，用于 __str__ 和 __repr__（参见表示）。

与主构造函数不同，这始终构造一个新对象。这种偏离主构造函数缓存行为的原因有二：流对象具有可变状态，因此确定两个输入是否相同是困难或不可能的，并且用户从文件构造时很可能明确希望从该文件而不是缓存加载。

与 ZoneInfo.no_cache 一样，通过此方法构造的对象不得添加到缓存中。

数据更新期间的行为

重要的是，给定 ZoneInfo 对象的行为在其生命周期内不得更改，因为 datetime 的 utcoffset() 方法用于其相等和哈希计算，如果结果在 datetime 的生命周期内发生变化，它可能会破坏所有可哈希对象的不变性 [3] [4]，即如果 x == y，则 hash(x) == hash(y) 也必须为真 [c]。

考虑到 datetime 不变性的维护以及主构造函数在用相同参数调用时始终返回相同对象的约定，如果在解释器运行期间时区数据源被更新，它不得使任何缓存失效或修改任何现有 ZoneInfo 对象。然而，新构造的 ZoneInfo 对象应来自更新后的数据源。

这意味着 ZoneInfo 构造函数的新调用更新数据源的时间点主要取决于缓存行为的语义。从更新后的数据源获取 ZoneInfo 对象的唯一保证方法是导致缓存未命中，方法是绕过缓存并使用 ZoneInfo.no_cache 或清除缓存。

主动缓存失效

除了允许用户 绕过 缓存的 ZoneInfo.no_cache 之外，ZoneInfo 还公开了一个 clear_cache 方法，以故意使整个缓存或缓存的选择性部分失效

ZoneInfo.clear_cache(*, only_keys: Iterable[str]=None) -> None

如果没有传递任何参数，所有缓存都会失效，并且在缓存清除后，对主 ZoneInfo 构造函数对每个键的第一次调用将返回一个新实例。

>>> NYC0 = ZoneInfo("America/New_York")
>>> NYC0 is ZoneInfo("America/New_York")
True
>>> ZoneInfo.clear_cache()
>>> NYC1 = ZoneInfo("America/New_York")
>>> NYC0 is NYC1
False
>>> NYC1 is ZoneInfo("America/New_York")
True

一个可选参数 only_keys 接受一个要从缓存中清除的键的可迭代对象，否则保持缓存不变。

>>> NYC0 = ZoneInfo("America/New_York")
>>> LA0 = ZoneInfo("America/Los_Angeles")
>>> ZoneInfo.clear_cache(only_keys=["America/New_York"])
>>> NYC1 = ZoneInfo("America/New_York")
>>> LA0 = ZoneInfo("America/Los_Angeles")
>>> NYC0 is NYC1
False
>>> LA0 is LA1
True

缓存行为的操作预计是一个小众用例；此函数主要用于方便测试，并允许具有特殊需求的用户根据其需求调整缓存失效行为。

字符串表示

ZoneInfo 类的 __str__ 表示将取自 key 参数。这部分是因为 key 代表字符串的人类可读“名称”，但也是因为它是一个用户希望公开的有用参数。有必要提供一种机制来公开键以进行语言之间的序列化，并且因为它也是 CLDR（Unicode Common Locale Data Repository [5]）等本地化项目的主键。

一个例子

>>> 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__

>>> zone = ZoneInfo.from_file(f)
>>> str(zone)
'ZoneInfo.from_file(<_io.BytesIO object at ...>)'

ZoneInfo 的 __repr__ 是实现定义的，并且在版本之间不一定稳定，但它不能是有效的 ZoneInfo 键，以避免键派生的 ZoneInfo 与有效 __str__ 和文件派生的 ZoneInfo（已回退到 __repr__）之间的混淆。

由于使用 str() 访问键无法轻松检查键是否存在（唯一的方法是尝试从中构造 ZoneInfo 并检测它是否引发异常），ZoneInfo 对象还将公开一个只读 key 属性，如果未提供键，该属性将为 None。

Pickle 序列化

ZoneInfo 对象将按键进行序列化，而不是序列化所有转换数据，并且从原始文件构造的 ZoneInfo 对象（即使指定了 key 值）也无法进行 pickle 序列化。

ZoneInfo 对象的行为取决于其构造方式

1. ZoneInfo(key)：当使用主构造函数构造时，ZoneInfo 对象将按键序列化，并且在反序列化时将在反序列化过程中使用主构造函数，因此预计与对同一时区的其他引用是相同的对象。例如，如果 europe_berlin_pkl 是一个包含从 ZoneInfo("Europe/Berlin") 构造的 pickle 的字符串，则预期行为如下

   >>> a = ZoneInfo("Europe/Berlin")
   >>> b = pickle.loads(europe_berlin_pkl)
   >>> a is b
   True
   

2. 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
   

3. ZoneInfo.from_file(fobj, /, key=None)：当从文件构造时，ZoneInfo 对象在 pickle 序列化时将引发异常。如果最终用户希望对从文件构造的 ZoneInfo 进行 pickle 序列化，建议他们使用包装类型或自定义序列化函数：要么按键序列化，要么存储文件对象的内容并序列化该内容。

这种序列化方法要求序列化和反序列化端都提供所需键的时区数据，类似于类和函数引用在序列化和反序列化环境中都应存在的方式。这也意味着，当对在具有不同版本时区数据的环境中序列化的 ZoneInfo 进行反序列化时，不保证结果的一致性。

系统时区信息

许多类 Unix 系统默认部署时区数据，或提供规范的时区数据包（通常称为 tzdata，就像在 Arch Linux、Fedora 和 Debian 上一样）。只要有可能，最好遵循系统时区信息，因为这允许所有语言栈的时区信息在一个地方更新和维护。鼓励 Python 分发商确保在可能的情况下（例如，通过将 tzdata 声明为 python 包的依赖项）与 Python 一起安装时区数据。

zoneinfo 模块将使用一种“搜索路径”策略，类似于 PATH 环境变量或 Python 中的 sys.path 变量；zoneinfo.TZPATH 变量将是只读的（有关更多详细信息，请参阅搜索路径配置），是时区数据位置的有序列表。当从键创建 ZoneInfo 实例时，时区文件将从路径上存在该键的第一个数据源构造，例如，如果 TZPATH 是

TZPATH = (
    "/usr/share/zoneinfo",
    "/etc/zoneinfo"
    )

并且（尽管这非常不寻常）/usr/share/zoneinfo 只包含 America/New_York，而 /etc/zoneinfo 包含 America/New_York 和 Europe/Moscow，那么 ZoneInfo("America/New_York") 将由 /usr/share/zoneinfo/America/New_York 满足，而 ZoneInfo("Europe/Moscow") 将由 /etc/zoneinfo/Europe/Moscow 满足。

目前，在 Windows 系统上，搜索路径将默认为空，因为 Windows 不官方提供时区数据库的副本。在非 Windows 系统上，搜索路径将默认为最常见的搜索路径列表。尽管这在未来版本中可能会改变，但发布时默认搜索路径将是

TZPATH = (
    "/usr/share/zoneinfo",
    "/usr/lib/zoneinfo",
    "/usr/share/lib/zoneinfo",
    "/etc/zoneinfo",
)

这可以在编译时或运行时配置；有关配置选项的更多信息，请参阅搜索路径配置。

tzdata Python 包

为了确保所有最终用户都能轻松访问时区数据，本 PEP 提议创建一个纯数据包 tzdata，作为系统数据不可用时的备用方案。tzdata 包将作为“第一方”包 [d] 在 PyPI 上分发，由 CPython 开发团队维护。

tzdata 包仅包含数据和元数据，不包含任何面向公众的函数或类。它将被设计为与较新的 importlib.resources [11] 访问模式和较旧的访问模式（如 pkgutil.get_data [12]）兼容。

虽然 tzdata 包明确设计用于 CPython，但它本身是一个公共包，可作为第三方 Python 包的“官方”时区数据源。

编译时选项

下游分发商最有可能确切知道他们的系统时区数据部署在哪里，因此将提供一个编译时选项 PYTHONTZPATH 来设置默认搜索路径。

PYTHONTZPATH 选项应该是一个由 os.pathsep 分隔的字符串，列出时区数据可能部署的位置（例如 /usr/share/zoneinfo）。

环境变量

在初始化 TZPATH 时（以及每次调用不带参数的 reset_tzpath 时），zoneinfo 模块将使用环境变量 PYTHONTZPATH（如果存在）来设置搜索路径。

PYTHONTZPATH 是一个由 os.pathsep 分隔的字符串，它 替换 （而不是增加）默认时区路径。以下是一些提议语义的示例

$ python print_tzpath.py
("/usr/share/zoneinfo",
 "/usr/lib/zoneinfo",
 "/usr/share/lib/zoneinfo",
 "/etc/zoneinfo")

$ PYTHONTZPATH="/etc/zoneinfo:/usr/share/zoneinfo" python print_tzpath.py
("/etc/zoneinfo",
 "/usr/share/zoneinfo")

$ PYTHONTZPATH="" python print_tzpath.py
()

这不提供内置机制来在默认搜索路径之前或之后添加路径，因为这些用例可能更小众。应该可以相当容易地使用默认搜索路径填充环境变量

$ export DEFAULT_TZPATH=$(python -c \
    "import os, zoneinfo; print(os.pathsep.join(zoneinfo.TZPATH))")

reset_tzpath 函数

zoneinfo 提供了一个 reset_tzpath 函数，允许在运行时更改搜索路径。

def reset_tzpath(
    to: Optional[Sequence[Union[str, os.PathLike]]] = None
) -> None:
    ...

当使用一系列路径调用时，此函数将 zoneinfo.TZPATH 设置为从所需值构造的元组。当不带参数或使用 None 调用时，此函数将 zoneinfo.TZPATH 重置为默认配置。

这可能主要用于（永久或临时）禁用系统时区路径的使用并强制模块使用 tzdata 包。改变 reset_tzpath 的操作可能不常见，除了在对时区配置敏感的测试函数中，但提供一种官方机制来改变它似乎比允许围绕 TZPATH 不可变性而产生大量黑客行为更好。

如构造函数所述，主 ZoneInfo 构造函数采用缓存以确保两个构造相同的 ZoneInfo 对象始终被比较为相同（即 ZoneInfo(key) is ZoneInfo(key)），并且此缓存的性质是实现定义的。这意味着在某些情况下，当 ZoneInfo 构造函数与相同 key 在不同 TZPATH 值下使用时，其行为可能不可预测地不一致。例如

>>> reset_tzpath(to=["/my/custom/tzdb"])
>>> a = ZoneInfo("My/Custom/Zone")
>>> reset_tzpath()
>>> b = ZoneInfo("My/Custom/Zone")
>>> del a
>>> del b
>>> c = ZoneInfo("My/Custom/Zone")

在此示例中，My/Custom/Zone 仅存在于 /my/custom/tzdb 中，而不存在于默认搜索路径中。在所有实现中，a 的构造函数必须成功。 b 的构造函数是否成功是实现定义的，但如果成功，则 a is b 必须为真，因为 a 和 b 都是对同一键的引用。c 的构造函数是否成功也是实现定义的。 zoneinfo 的实现 可以 返回在先前构造函数调用中构造的对象，或者它们可能因异常而失败。

反对将 ZoneInfo 直接放入 datetime 的论点

datetime 模块已经有些拥挤，因为它有许多行为复杂的类——datetime.datetime、datetime.date、datetime.time、datetime.timedelta、datetime.timezone 和 datetime.tzinfo。该模块的实现和文档已经相当复杂，如果能避免加剧问题，最好不要这样做。

ZoneInfo 类在某些方面也不同于 datetime 提供的所有其他类；其他类都旨在成为精简、简单的数据类型，而 ZoneInfo 类更复杂：它是一个特定格式 (TZif) 的解析器，是该格式中存储信息的表示，以及在系统中已知位置查找信息的机制。

最后，虽然需要 zoneinfo 模块的人也需要 datetime 模块，但反之则不一定：许多人希望在没有 zoneinfo 的情况下使用 datetime。考虑到 zoneinfo 可能会引入额外的、可能更重量级的标准库模块，最好允许两者分开导入——特别是如果 Python 的未来有可能出现“tree shaking”分发。[9]

最终分析表明，将 zoneinfo 保持为一个独立的模块，并拥有独立的文档页面，而不是将其类和函数直接放入 datetime 中，是最好的选择。

使用 datetime.zoneinfo 而不是 zoneinfo

更可接受的配置可能是将 zoneinfo 作为 datetime 下的一个模块进行嵌套，即 datetime.zoneinfo。

支持此观点的论点

1. 它巧妙地将 zoneinfo 和 datetime 命名空间关联起来
2. timezone 类已经在 datetime 中，而一些时区在 datetime 中，另一些在顶级模块中，这可能看起来很奇怪。
3. 如前所述，导入 zoneinfo 必然需要导入 datetime，因此要求导入父模块并非强加。

反对这个的论点

1. 为了避免强制所有 datetime 用户导入 zoneinfo，zoneinfo 模块需要进行惰性导入，这意味着最终用户需要明确导入 datetime.zoneinfo（而不是导入 datetime 并访问模块上的 zoneinfo 属性）。这是 dateutil 的工作方式（所有子模块都是惰性导入的），这对于最终用户来说是一个长期存在的困惑来源。

   可以通过使用模块级别的 __getattr__ 和 __dir__ (遵循 PEP 562) 来避免最终用户这种令人困惑的要求，但这会增加 datetime 模块实现的复杂性。模块或类中的这种行为往往会混淆静态分析工具，这对于像 datetime 这样广泛使用和关键的库来说可能不是理想的。

2. 将实现嵌套在 datetime 下可能需要将 datetime 从单个文件模块 (datetime.py) 重组为带有 __init__.py 的目录。这是一个次要问题，但 datetime 模块的结构已经稳定多年，如果可能的话，最好避免改动。

   通过将 zoneinfo 实现为 _zoneinfo.py 并在 datetime 内部将其导入为 zoneinfo，可以 缓解这种担忧，但这从美学或代码组织的角度来看似乎不可取，并且会排除最终用户需要显式导入 datetime.zoneinfo 的嵌套版本。

本 PEP 认为，总体而言，最好使用一个单独的顶级 zoneinfo 模块，因为嵌套的好处并没有大到足以压倒实际的实现问题。