zoneinfo --- IANA タイムゾーンのサポート

Added in version 3.9.

ソースコード: Lib/zoneinfo

zoneinfo モジュールは PEP 615 で規定された、IANAのタイムゾーンデータベースをサポートした具体的なタイムゾーン実装を提供します。 デフォルトでは、zoneinfo はシステムのタイムゾーンデータが利用可能であれば使用します。システムのタイムゾーンデータが利用できない場合、ライブラリはPyPIにあるファーストパーティーのパッケージ tzdata を代わりに使用します。

参考

モジュール: datetime

ZoneInfo クラスを使用するように設計されたデータ型 time と datetime を提供します。

tzdata パッケージ

CPythonコアデベロッパーによってメンテナンスされているファーストパーティーのパッケージ。タイムゾーンデータを供給し、PyPIで配布されている。

Availability: not WASI.

このモジュールは WebAssembly では動作しないか、利用不可です。詳しくは、WebAssembly プラットフォーム を見てください。

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

データソース

The zoneinfo module does not directly provide time zone data, and instead pulls time zone information from the system time zone database or the first-party PyPI package tzdata, if available. Some systems, including notably Windows systems, do not have an IANA database available, and so for projects targeting cross-platform compatibility that require time zone data, it is recommended to declare a dependency on tzdata. If neither system data nor tzdata are available, all calls to ZoneInfo will raise ZoneInfoNotFoundError.

Налаштування джерел даних

Коли викликається ZoneInfo(key), конструктор спочатку шукає файл, який відповідає key, у каталогах, указаних у TZPATH, а в разі помилки шукає відповідність у пакеті tzdata. Цю поведінку можна налаштувати трьома способами:

  1. Типовий TZPATH, якщо не вказано інше, можна налаштувати під час компіляції.

  2. TZPATH можна налаштувати за допомогою змінної середовища.

  3. У runtime шляхом пошуку можна маніпулювати за допомогою функції reset_tzpath().

Конфігурація під час компіляції

The default TZPATH includes several common deployment locations for the time zone database (except on Windows, where there are no "well-known" locations for time zone data). On POSIX systems, downstream distributors and those building Python from source who know where their system time zone data is deployed may change the default time zone path by specifying the compile-time option TZPATH (or, more likely, the configure flag --with-tzpath), which should be a string delimited by 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)

文字列 key でIANAタイムゾーンを指定した、具体的な datetime.tzinfo のサブクラス。Calls to the primary constructor will always return objects that compare identically; put another way, barring cache invalidation via ZoneInfo.clear_cache(), for all values of key, the following assertion will always be true:

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

key має бути у формі відносного нормалізованого шляху POSIX без посилань верхнього рівня. Конструктор викличе ValueError, якщо передано невідповідний ключ.

key に一致するファイルが見つからない場合、コンストラクタは ZoneInfoNotFoundError を送出します。

ZoneInfo クラスには2つの別のコンストラクターがあります:

classmethod ZoneInfo.from_file(file_obj, /, key=None)

file-like オブジェクトが返すbytes（バイナリーモードで開いたファイルや io.BytesIO オブジェクト）から ZoneInfo オブジェクトを構築します。一次コンストラクタと異なり、常に新規オブジェクトを構築します。

Параметр key встановлює назву зони для цілей __str__() і __repr__().

このコンストラクタで生成したオブジェクトはpickle化できません（pickling を参照）。

classmethod ZoneInfo.no_cache(key)

Альтернативний конструктор, який обходить кеш конструктора. Він ідентичний основному конструктору, але повертає новий об’єкт під час кожного виклику. Це, швидше за все, буде корисним для тестування чи демонстрації, але його також можна використовувати для створення системи з іншою стратегією анулювання кешу.

Об’єкти, створені за допомогою цього конструктора, також обійдуть кеш процесу десеріалізації, коли їх не буде вибрано.

注意

Використання цього конструктора може дивовижним чином змінити семантику ваших дат і часів, використовуйте його, лише якщо ви знаєте, що вам це потрібно.

次のクラスメソッドもサポートされています:

classmethod ZoneInfo.clear_cache(*, only_keys=None)

Метод анулювання кешу в класі ZoneInfo. Якщо аргументи не передано, усі кеші стають недійсними, а наступний виклик основного конструктора для кожного ключа поверне новий екземпляр.

Якщо в параметр only_keys передається ітерація імен ключів, з кешу буде видалено лише вказані ключі. Ключі, передані в only_keys, але не знайдені в кеші, ігноруються.

警告

Invoking this function may change the semantics of datetimes using ZoneInfo in surprising ways; this modifies module state and thus may have wide-ranging effects. Only use it if you know that you need to.

Клас має один атрибут:

ZoneInfo.key

Це лише для читання attribute, який повертає значення key, переданого конструктору, який має бути ключем пошуку в базі даних часового поясу IANA (наприклад, America/New_York, Європа/Париж або Азія/Токіо).

Для зон, створених із файлу без зазначення параметра key, буде встановлено None.

注釈

Хоча надавати їх кінцевим користувачам є досить поширеною практикою, ці значення призначені як первинні ключі для представлення відповідних зон, а не обов’язково для елементів, спрямованих на користувача. Такі проекти, як CLDR (загальне сховище даних Unicode Common Locale Data Repository), можна використовувати для отримання більш зручних рядків із цих ключів.

文字列表現

Рядкове представлення, що повертається під час виклику 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(). Repr ZoneInfo визначається реалізацією і не обов’язково є стабільним між версіями, але гарантовано, що він не є дійсним ключем ZoneInfo.

Серіалізація соління

Замість того, щоб серіалізувати всі дані переходу, об’єкти ZoneInfo серіалізуються за ключем, а об’єкти ZoneInfo, створені з файлів (навіть ті, у яких указано значення key), не можуть бути мариновані.

Поведінка файлу ZoneInfo залежить від того, як він був створений:

  1. ZoneInfo(key): коли створюється за допомогою первинного конструктора, об’єкт ZoneInfo серіалізується за ключем, а коли десеріалізується, процес десеріалізації використовує первинний, тому очікується, що вони будуть той самий об’єкт, що й інші посилання на той самий часовий пояс. Наприклад, якщо europe_berlin_pkl - це рядок, що містить маринований пікле, створений з 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 - це рядок, що містить маринований пікле, побудований з ZoneInfo.no_cache("Europe/Berlin"), можна очікувати такої поведінки:

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

  3. ZoneInfo.from_file(file_obj, /, key=None): When constructed from a file, the ZoneInfo object raises an exception on pickling. If an end user wants to pickle a ZoneInfo constructed from a file, it is recommended that they use a wrapper type or a custom serialization function: either serializing by key or storing the contents of the file object and serializing that.

Цей метод серіалізації вимагає, щоб дані часового поясу для необхідного ключа були доступні як на стороні серіалізації, так і на стороні десеріалізації, подібно до того, як очікуються посилання на класи та функції в середовищах серіалізації та десеріалізації. Це також означає, що не надається жодних гарантій щодо узгодженості результатів під час видалення ZoneInfo, вибраного в середовищі з іншою версією даних часового поясу.

関数

zoneinfo.available_timezones()

Отримайте набір, що містить усі дійсні ключі для часових поясів IANA, доступних будь-де на шляху часового поясу. Це перераховується під час кожного виклику функції.

Ця функція включає лише канонічні назви зон і не включає "спеціальні" зони, такі як ті, що знаходяться в каталогах posix/ і right/ або зона posixrules.

注意

Ця функція може відкрити велику кількість файлів, оскільки найкращий спосіб визначити, чи є файл на шляху до часового поясу дійсним часовим поясом, це прочитати "магічний рядок" на початку.

注釈

Ці значення не призначені для надання кінцевим користувачам; для елементів, які відкриваються користувачам, програми повинні використовувати щось на зразок CLDR (сховище даних Unicode Common Locale), щоб отримати більш зручні рядки. Дивіться також застереження щодо 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 містить недійсний компонент, який буде відфільтровано, наприклад відносний шлях.