zoneinfo — поддержка часовых поясов IANA

Использование ZoneInfo

ZoneInfo — конкретная реализация абстрактного базового класса datetime.tzinfo. Предполагается, что этот класс будет присоединён к tzinfo — через конструктор, метод datetime.replace или datetime.astimezone:

>>> from zoneinfo import ZoneInfo
>>> import datetime as dt

>>> when = dt.datetime(2020, 10, 31, 12, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(when)
2020-10-31 12:00:00-07:00

>>> when.tzname()
'PDT'

Объекты datetime, созданные таким образом, совместимы с арифметическими операциями над датами и временем и обрабатывают переходы на летнее время без дополнительных действий:

>>> when_add = when + dt.timedelta(days=1)

>>> print(when_add)
2020-11-01 12:00:00-08:00

>>> when_add.tzname()
'PST'

Эти часовые пояса также поддерживают атрибут fold, введённый в PEP 495. При переходах смещения, приводящих к неоднозначности времени (например, при переходе с летнего времени на стандартное), используется смещение, действовавшее до перехода, если fold=0, и смещение, действующее после перехода, если fold=1. Например:

>>> when = dt.datetime(2020, 11, 1, 1, tzinfo=ZoneInfo("America/Los_Angeles"))
>>> print(when)
2020-11-01 01:00:00-07:00

>>> print(when.replace(fold=1))
2020-11-01 01:00:00-08:00

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

>>> LOS_ANGELES = ZoneInfo("America/Los_Angeles")
>>> when_utc = dt.datetime(2020, 11, 1, 8, tzinfo=dt.timezone.utc)

>>> # Before the PDT -> PST transition
>>> print(when_utc.astimezone(LOS_ANGELES))
2020-11-01 01:00:00-07:00

>>> # After the PDT -> PST transition
>>> print((when_utc + dt.timedelta(hours=1)).astimezone(LOS_ANGELES))
2020-11-01 01:00:00-08:00

Источники данных

Модуль zoneinfo напрямую не предоставляет данные о часовых поясах, а вместо этого получает сведения о часовых поясах из системной базы данных или из пакета tzdata на 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(file_obj, /, key=None)

Создаёт объект ZoneInfo из файлового объекта, возвращающего байты (например, из файла, открытого в двоичном режиме, или объекта io.BytesIO). В отличие от основного конструктора, этот конструктор всегда создаёт новый объект.

Параметр key задаёт имя часового пояса для методов __str__() и __repr__().

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

Если данные, прочитанные из file_obj, не являются допустимым файлом TZif, вызывается ValueError.

classmethod ZoneInfo.no_cache(key)

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

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

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

Использование этого конструктора может неожиданным образом изменить семантику объектов 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 (Common Locale Data Repository — общий репозиторий данных локалей Unicode), позволяют получать более понятные пользователям строки на основе этих ключей.

>>> zone = ZoneInfo("Pacific/Kwajalein")
>>> str(zone)
'Pacific/Kwajalein'

>>> when = dt.datetime(2020, 4, 1, 3, 15, tzinfo=zone)
>>> f"{when.isoformat()} [{when.tzinfo}]"
'2020-04-01T03:15:00+12:00 [Pacific/Kwajalein]'

Функции

zoneinfo.available_timezones()

Возвращает множество всех допустимых ключей часовых поясов IANA, доступных в любом месте пути поиска часовых поясов. При каждом вызове функции множество вычисляется заново.

Эта функция включает только канонические имена часовых поясов и не включает «специальные» часовые пояса, например из каталогов posix/ и right/, или часовой пояс posixrules.

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

Эта функция может открывать большое количество файлов, так как лучший способ определить, является ли файл в пути поиска допустимым файлом часового пояса, — прочитать «магическую строку» в его начале.

Примечание

Эти значения не предназначены для показа конечным пользователям; для пользовательских интерфейсов приложениям следует использовать, например, CLDR (Common Locale Data Repository — общий репозиторий данных локалей 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 содержит недопустимую компоненту, которая будет отфильтрована, например относительный путь.