zoneinfo — Поддержка часовых поясов IANA

Использование 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'

Созданные таким образом значения времени совместимы с арифметикой datetime и обрабатывают переходы на летнее/зимнее время без дополнительного вмешательства:

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

При преобразовании из другого часового пояса значение fold будет установлено в правильное значение:

>>> 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 напрямую не предоставляет данные о часовых поясах, а вместо этого извлекает информацию о часовых поясах из базы данных часовых поясов системы или пакета tzdata от PyPI, если он доступен. Некоторые системы, в частности системы 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 (см. сериализацию pickle).

classmethod ZoneInfo.no_cache(key)

Альтернативный конструктор, который обходит кэш конструктора. Он идентичен первичному конструктору, но возвращает новый объект при каждом вызове. Это, скорее всего, будет полезно для тестирования или демонстрации, но также может быть использовано для создания системы с другой стратегией отмены кэширования.

Объекты, созданные с помощью этого конструктора, также обойдут кэш процесса десериализации при распаковке.

Внимание

Использование этого конструктора может неожиданным образом изменить семантику ваших дат и времён; используйте его только если вы точно знаете, что вам это нужно.

Также доступны следующие методы класса:

classmethod ZoneInfo.clear_cache(*, only_keys=None)

Метод для отмены кэширования в классе ZoneInfo. Если не передано никаких аргументов, все кэши аннулируются, и следующий вызов первичного конструктора для каждого ключа вернёт новую инстанцию.

Если в параметр only_keys передаётся итерируемый список имён ключей, будут удалены только указанные ключи из кэша. Ключи, переданные в only_keys, но не найденные в кэше, игнорируются.

Предупреждение

Вызов этой функции может неожиданным образом изменить семантику дат и времён, использующих ZoneInfo; это изменяет глобальное состояние процесса и, следовательно, может иметь широкий спектр последствий. Используйте его только если вы точно знаете, что вам это нужно.

Класс имеет одно свойство:

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 вместо импорта TZPATH из zoneinfo или присвоения долгоживущей переменной zoneinfo.TZPATH.

Дополнительную информацию о настройке пути поиска часовых поясов см. в Настройка источников данных.

Исключения и предупреждения

exception zoneinfo.ZoneInfoNotFoundError

Выбрасывается, когда построение объекта ZoneInfo терпит неудачу, потому что указанный ключ не был найден в системе. Это подкласс KeyError.

exception zoneinfo.InvalidTZPathWarning

Выбрасывается, когда PYTHONTZPATH содержит недействительный компонент, который будет отфильтрован, например, относительный путь.