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

При преобразовании из другого часового пояса для 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(file_obj, /, key=None)

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

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

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

classmethod ZoneInfo.no_cache(key)

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

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

Внимание

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

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

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