zoneinfo --- IANA 時區支援¶

使用 ZoneInfo¶

ZoneInfo 是 datetime.tzinfo 抽象基底類別的一個具體實作，旨在透過建構函式、datetime.replace 方法或 datetime.astimezone 方法附加到 tzinfo：

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

以此方式建構的 Datetime 物件與 datetime 運算相容，並能處理日光節約時間轉換而無需進一步干預：

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

>>> # 在 PDT 轉換為 PST 之前
>>> print(dt_utc.astimezone(LOS_ANGELES))
2020-11-01 01:00:00-07:00

>>> # 在 PDT 轉換為 PST 之後
>>> 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 子類別，代表由字串 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(file_obj, /, key=None)¶

從回傳位元組的類檔案物件（例如以二進位模式開啟的檔案或一個 io.BytesIO 物件）建構一個 ZoneInfo 物件。與主要建構函式不同，這個建構函式總是會建構一個新物件。

key 參數設定了時區的名稱，用於 __str__() 和 __repr__()。

透過此建構函式建立的物件無法被封裝（參閱 pickling）。

classmethod ZoneInfo.no_cache(key)¶

一個繞過建構函式快取的備用建構函式。它與主要建構函式相同，但每次呼叫都會回傳一個新物件。這對於測試或示範目的最可能有用，但它也可以用來建立一個具有不同快取失效策略的系統。

透過此建構函式建立的物件，在拆封時也會繞過去序列化過程的快取。

警示

使用此建構函式可能會以意想不到的方式改變你的 datetime 物件的語意，只有在你確定需要時才使用它。

以下類別方法也可用：

classmethod ZoneInfo.clear_cache(*, only_keys=None)¶

一個用於使 ZoneInfo 類別上的快取失效的方法。如果沒有傳入引數，所有快取都會失效，且下一次對每個鍵的主要建構函式呼叫都將回傳一個新的實例。

如果將一個包含鍵名的可疊代物件傳遞給 only_keys 參數，則只有指定的鍵會從快取中移除。傳遞給 only_keys 但在快取中找不到的鍵會被忽略。

警告

呼叫此函式可能會以意想不到的方式改變使用 ZoneInfo 的 datetime 物件的語意；這會修改模組狀態，因此可能產生廣泛的影響。只有在你確定需要時才使用它。

該類別有一個屬性：

ZoneInfo.key¶

這是一個唯讀 屬性，它回傳傳遞給建構函式的 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 參數必須是一個由字串或 os.PathLike 組成的 序列，而不是一個字串，其中所有元素都必須是絕對路徑。如果傳入的不是絕對路徑，將會引發 ValueError 例外。

全域變數¶

zoneinfo.TZPATH¶

一個表示時區搜尋路徑的唯讀序列 —— 當從一個鍵建構 ZoneInfo 時，該鍵會與 TZPATH 中的每個條目結合，並使用找到的第一個檔案。

TZPATH 只能包含絕對路徑，絕不能包含相對路徑，無論如何設定。

zoneinfo.TZPATH 指向的物件可能會因應對 reset_tzpath() 的呼叫而改變，因此建議使用 zoneinfo.TZPATH，而不是從 zoneinfo 引入 TZPATH 或將一個長生命週期的變數賦值給 zoneinfo.TZPATH。

有關設定時區搜尋路徑的更多資訊，請參閱 設定資料來源。

例外與警告¶

exception zoneinfo.ZoneInfoNotFoundError¶

當建構 ZoneInfo 物件因在系統上找不到指定的鍵而失敗時引發。這是 KeyError 的一個子類別。

exception zoneinfo.InvalidTZPathWarning¶

當 PYTHONTZPATH 包含將被過濾掉的無效元件（例如相對路徑）時引發。