构造函数

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

ZoneInfo(key: str)

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

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

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

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

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

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

ZoneInfo.no_cache(key: str)

这是一个绕过构造函数缓存的备用构造函数。它与主构造函数相同，但在每次调用时都返回一个新对象。这可能最适合测试目的，或者有意在具有相同名义时区的日期时间之间引入“不同时区”的语义。

即使通过此方法构造的对象本来应该是一个缓存未命中，它也不得被放入缓存中；换句话说，以下断言应该始终为真

>>> 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__ 设置时区的名称（请参阅 Representations）。

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

与 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 通用语言环境数据存储库 [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 键，以避免在具有有效 __str__ 的键派生 ZoneInfo 和已落入 __repr__ 的文件派生 ZoneInfo 之间产生混淆。

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

Pickle 序列化

与其序列化所有转换数据，不如通过键序列化 ZoneInfo 对象，并且从原始文件（即使是为 key 指定了值的那些文件）构造的 ZoneInfo 对象不能被 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 对象将在 pickling 时引发异常。如果最终用户希望 pickle 从文件构造的 ZoneInfo，建议他们使用包装器类型或自定义序列化函数：通过键序列化或存储文件对象的内容并序列化该内容。

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

系统时区信息

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

zoneinfo 模块将使用类似于 PATH 环境变量或 Python 中的 sys.path 变量的“搜索路径”策略；zoneinfo.TZPATH 变量将是只读的（有关更多详细信息，请参阅 search-path-config），按顺序排列要搜索的时区数据位置列表。当从键创建 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",
)

这可以在编译时或运行时配置；有关配置选项的更多信息，请参阅 search-path-config。

tzdata Python 包

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

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

虽然它是专门为 CPython 使用而设计的，但 tzdata 包旨在成为一个独立的公共包，它可以用作第三方 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不变性的hack更好。

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

>>> 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模块，因为嵌套的好处并不大到足以压倒实际的实现问题。