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 не предоставляет данные часовых поясов напрямую, а получает сведения о часовых поясах из системной базы данных часовых поясов или из пакета tzdata, распространяемого разработчиками Python через 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)

Альтернативный конструктор, обходящий кэш конструктора. Он идентичен основному конструктору, но при каждом вызове возвращает новый объект. В первую очередь он может пригодиться для тестирования или демонстрации, но его также можно использовать для создания системы с другой стратегией очистки кэша.

При десериализации объекты, созданные с помощью этого конструктора, также обходят кэш.

Внимание

Использование этого конструктора может неожиданным образом изменить семантику ваших объектов datetime. Используйте его, только если уверены, что он вам необходим.

Также доступны следующие методы класса:

classmethod ZoneInfo.clear_cache(*, only_keys=None)

Метод для очистки кэша класса ZoneInfo. Если аргументы не переданы, очищаются все кэши, и следующий вызов основного конструктора для каждого ключа вернёт новый экземпляр.

Если в параметр only_keys передан итерируемый объект с именами ключей, из кэша будут удалены только указанные ключи. Ключи, переданные в only_keys, но не найденные в кэше, игнорируются.

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

Вызов этой функции может неожиданным образом изменить семантику объектов datetime, использующих 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 содержит недопустимый компонент, который будет отфильтрован, например относительный путь.