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

Объекты, созданные с помощью этого конструктора, не могут быть сериализованы с помощью пиклирования (см. pickling).

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