zoneinfo — підтримка часового поясу IANA

Added in version 3.9.

Source code: Lib/zoneinfo

The zoneinfo module provides a concrete time zone implementation to support the IANA time zone database as originally specified in PEP 615. By default, zoneinfo uses the system’s time zone data if available; if no system time zone data is available, the library will fall back to using the first-party tzdata package available on PyPI.

Дивись також

Модуль: datetime

Надає типи time і datetime, з якими призначений клас ZoneInfo.

Package tzdata

Пакет першої сторони, який підтримується розробниками ядра CPython для надання даних про часовий пояс через PyPI.

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssembly platforms for more information.

Використання 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().

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

За замовчуванням TZPATH містить кілька поширених місць розгортання бази даних часових поясів (за винятком Windows, де немає «добре відомих» місць для даних часових поясів). У системах POSIX розповсюджувачі нижньої течії та ті, хто створює Python із джерела, які знають, де розгортаються дані часових поясів у їхній системі, можуть змінити шлях часового поясу за замовчуванням, вказавши параметр під час компіляції TZPATH (або, що ймовірніше, параметр configure flag --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, якщо передано невідповідний ключ.

Якщо не знайдено жодного файлу, що відповідає ключу, конструктор викличе ZoneInfoNotFoundError.

Клас ZoneInfo має два альтернативних конструктори:

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

Створює об’єкт ZoneInfo з файлоподібного об’єкта, який повертає байти (наприклад, файл, відкритий у двійковому режимі, або об’єкт io.BytesIO). На відміну від первинного конструктора, це завжди створює новий об’єкт.

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

Об’єкти, створені за допомогою цього конструктора, не можуть бути протравлені (див. 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(fobj, /, key=None): коли створено з файлу, об’єкт ZoneInfo викликає виключення під час травлення. Якщо кінцевий користувач хоче вибрати ZoneInfo, створений з файлу, рекомендується використовувати тип оболонки або спеціальну функцію серіалізації: або серіалізація за ключем, або збереження вмісту об’єкта файлу та його серіалізація.

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