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'

Временные метки, созданные таким образом, совместимы с арифметикой дат и времени и обрабатывают переходы к летнему/зимнему времени без дополнительного вмешательства:

>>> 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 tzdata, если он доступен. Некоторые системы, в том числе, в частности, 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 содержит недопустимый компонент, который будет отфильтрован, например, относительный путь.