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 совместимы с арифметикой 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 Common Locale Data Repository), могут быть использованы для получения более удобных для пользователя строк из этих ключей.

>>> 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 Common Locale Data Repository) для получения более удобных для пользователя строк. См. также предупреждающее примечание о 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 содержит недопустимый компонент, который будет отфильтрован, например, относительный путь.