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

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公共区域设置数据存储库）这样的项目可以用来从这些键中获取更多用户友好的字符串。

>>> 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]'

功能

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 包含将被筛选出的无效组件，例如相对路径。