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__().

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

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