zoneinfo ---IANA时区支持

3.9 新版功能.

---

这个 zoneinfo 模块提供了一个具体的时区实现，以支持最初在 PEP 615 . 默认情况下， zoneinfo 使用系统的时区数据（如果可用）；如果没有可用的系统时区数据，库将返回到使用第一方 tzdata PyPI上提供的软件包。

参见

模块： datetime

提供 time 和 datetime 使用的类型 ZoneInfo 类是为使用而设计的。

包裹 tzdata

CPython核心开发人员维护的第一方包，用于通过PyPI提供时区数据。

使用 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'

这些时区还支持 fold 属性引入 PEP 495 . 在导致时间不明确的偏移转换（例如夏令时到标准时间转换）期间，从 之前 转换用于 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

从其他时区转换时，折叠将设置为正确的值：

>>> 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包中查找匹配项。此行为可以通过三种方式进行配置：

1. 默认值 TZPATH 如果未另行指定，则可以在 compile time .

2. TZPATH 可以使用配置 an environment variable .

3. AT runtime ，可以使用 reset_tzpath() 功能。

编译时配置

默认值 TZPATH 包括时区数据库的几个常见部署位置（除了在Windows上，没有时区数据的“已知”位置）。在POSIX系统上，下游分发服务器和从源代码构建Python的那些知道系统时区数据部署在哪里的人可以通过指定编译时选项来更改默认时区路径 TZPATH （或者，更可能的是 configure 旗帜 --with-tzpath )，它应该是由 os.pathsep .

在所有平台上，配置的值都可用作 TZPATH 键入 sysconfig.get_config_var() .

环境配置

初始化时 TZPATH （无论是在导入时还是在任何时候 reset_tzpath() 调用时没有参数） zoneinfo 模块将使用环境变量 PYTHONTZPATH ，如果存在，则设置搜索路径。

PYTHONTZPATH

这是一个 os.pathsep -包含要使用的时区搜索路径的分隔字符串。它必须只包含绝对路径而不是相对路径。中指定的相关组件 PYTHONTZPATH 将不使用，否则指定相对路径时的行为是实现定义的；CPython将引发 InvalidTZPathWarning ，但其他实现可以自动忽略错误的组件或引发异常。

要将系统设置为忽略系统数据并改用tzdata包，请设置 PYTHONTZPATH="" .

运行时配置

TZ搜索路径也可以在运行时使用 reset_tzpath() 功能。这通常不是一个明智的操作，尽管在需要使用特定时区路径（或需要禁用对系统时区的访问）的测试函数中使用它是合理的。

这个 ZoneInfo 类

class zoneinfo.ZoneInfo(key)

混凝土 datetime.tzinfo 表示由字符串指定的IANA时区的子类 key . 对主构造函数的调用将始终返回相同比较的对象；换句话说，通过 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)

构建一个 ZoneInfo 从类似文件的对象返回字节（例如以二进制模式打开的文件或 io.BytesIO 对象）。与主构造函数不同，它总是构造一个新对象。

这个 key 参数设置区域的名称，以便 __str__() 和 __repr__() .

无法pickle通过此构造函数创建的对象（请参见 pickling ）

classmethod ZoneInfo.no_cache(key)

绕过构造函数缓存的备用构造函数。它与主构造函数相同，但在每次调用时都返回一个新对象。这对于测试或演示非常有用，但也可以用于创建具有不同缓存失效策略的系统。

通过此构造函数创建的对象在取消选中时也将绕过反序列化进程的缓存。

警告

使用此构造函数可能会以令人惊讶的方式更改日期时间的语义，只有在知道需要时才使用它。

以下类方法也可用：

classmethod ZoneInfo.clear_cache(*, only_keys=None)

使缓存失效的方法 ZoneInfo 上课。如果没有传递任何参数，则所有缓存都将失效，并且对每个键的主构造函数的下一次调用将返回一个新实例。

如果向 only_keys 参数，只有指定的键将从缓存中删除。传递给的密钥 only_keys 但在缓存中找不到将被忽略。

警告

调用此函数可能会使用 ZoneInfo 以令人惊讶的方式；这改变了整个过程的全局状态，因此可能产生广泛的影响。只有当你知道你需要的时候才使用它。

类有一个属性：

ZoneInfo.key

这是只读的 attribute 返回的值 key 传递给构造函数，该构造函数应该是IANA时区数据库中的查找键（例如。 America/New_York ， Europe/Paris 或 Asia/Tokyo ）

对于不指定 key 参数，将设置为 None .

注解

尽管向最终用户公开这些值是一种比较常见的做法，但这些值被设计为表示相关区域的主键，而不一定是面向用户的元素。像CLDR（Unicode公共区域设置数据存储库）这样的项目可以用来从这些键中获取更多用户友好的字符串。

字符串表示

调用时返回的字符串表示形式 str 在一 ZoneInfo 对象默认使用 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 文件取决于其构造方式：

1. ZoneInfo(key) ：使用主构造函数构造时 ZoneInfo 对象是按键序列化的，反序列化时，反序列化进程使用主对象，因此预期这些对象与对同一时区的其他引用是同一对象。例如，如果 europe_berlin_pkl 包含pickle的字符串 ZoneInfo("Europe/Berlin") ，可能会出现以下行为：

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

2. ZoneInfo.no_cache(key) ：从缓存绕过构造函数构造时 ZoneInfo 对象也按键序列化，但在反序列化时，反序列化进程使用缓存绕过构造函数。如果 europe_berlin_pkl_nc 包含pickle的字符串 ZoneInfo.no_cache("Europe/Berlin") ，可能会出现以下行为：

   >>> a = ZoneInfo("Europe/Berlin")
   >>> b = pickle.loads(europe_berlin_pkl_nc)
   >>> a is b
   False
   

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

这种序列化方法要求所需密钥的时区数据在序列化和反序列化端都可用，类似于在序列化和反序列化环境中预期存在对类和函数的引用的方式。这也意味着，在取消选中一个 ZoneInfo 在具有不同版本时区数据的环境中进行pickle。

功能

zoneinfo.available_timezones()

获取一个集合，该集合包含时区路径上任何位置可用的IANA时区的所有有效键。每次调用函数时都会重新计算此值。

此函数仅包括规范区域名，不包括“特殊”区域，如 posix/ 和 right/ 目录，或 posixrules 区域。

警告

此函数可以打开大量文件，因为确定时区路径上的文件是否为有效时区的最佳方法是读取开头的“魔术字符串”。

注解

这些值不是设计为向最终用户公开的；对于面向用户的元素，应用程序应该使用CLDR（Unicode公共区域设置数据存储库）之类的方法来获得用户友好的字符串。另请参见 ZoneInfo.key .

zoneinfo.reset_tzpath(to=None)

设置或重置时区搜索路径 (TZPATH )对于模块。当没有争论的时候， TZPATH 设置为默认值。

调用 reset_tzpath 不会使 ZoneInfo 缓存，以及对主服务器的调用 ZoneInfo 构造函数将只使用新的 TZPATH 以防缓存未命中。

这个 to 参数必须是 sequence 弦或 os.PathLike 而不是字符串，所有字符串都必须是绝对路径。 ValueError 如果传递的不是绝对路径，则将引发。

全球性的

zoneinfo.TZPATH

表示时区搜索路径的只读序列——在构造 ZoneInfo 从一个键，该键连接到 TZPATH ，并使用找到的第一个文件。

TZPATH 可能只包含绝对路径，而不包含相对路径，无论它是如何配置的。

对象 zoneinfo.TZPATH 指向可能因响应调用而更改 reset_tzpath() ，因此建议使用 zoneinfo.TZPATH 而不是进口 TZPATH 从 zoneinfo 或者为 zoneinfo.TZPATH .

有关配置时区搜索路径的详细信息，请参阅 配置数据源 .

例外和警告

exception zoneinfo.ZoneInfoNotFoundError

在建造 ZoneInfo 对象失败，因为在系统上找不到指定的密钥。这是 KeyError .

exception zoneinfo.InvalidTZPathWarning

提出时 PYTHONTZPATH 包含将被筛选出的无效组件，例如相对路径。