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

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

>>> 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. Если ни те, ни другие системные данные не доступны, все вызовы 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, но не найденные в кэше, игнорируются.

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

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

У класса есть один атрибут:

ZoneInfo.key¶

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