zoneinfo – поддержка часовых поясов IANA¶zoneinfo – IANA time zone support

Использование ZoneInfo¶Using 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, созданные таким образом, совместимы с арифметикой 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)

>>> # Перед переходом с PDT на PST
>>> print(dt_utc.astimezone(LOS_ANGELES))
2020-11-01 01:00:00-07:00

>>> # После перехода с PDT на PST
>>> print((dt_utc + timedelta(hours=1)).astimezone(LOS_ANGELES))
2020-11-01 01:00:00-08:00

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

Модуль zoneinfo не предоставляет данные о часовых поясах напрямую, а получает информацию о часовых поясах из системной базы данных часовых поясов или из основного пакета PyPI tzdata, если он доступен. Некоторые системы, в частности Windows, не имеют базы данных IANA, поэтому для проектов, нацеленных на кроссплатформенную совместимость и требующих данные о часовых поясах, рекомендуется объявить зависимость от tzdata. Если ни системные данные, ни tzdata недоступны, все вызовы ZoneInfo будут вызывать ZoneInfoNotFoundError.

Класс ZoneInfo¶The ZoneInfo class

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

Объекты, созданные через этот конструктор, не могут быть pickled (см. pickling).

classmethod ZoneInfo.no_cache(key)¶

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

Объекты, созданные через этот конструктор, также будут обходить кеш процесса десериализации при десериализации (unpickled).

Внимание

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

>>> 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]'

Функции¶Functions

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

Глобальные переменные¶Globals

zoneinfo.TZPATH¶

Последовательность только для чтения, представляющая путь поиска временной зоны: при создании ZoneInfo по ключу ключ объединяется с каждым элементом в TZPATH, и используется первый найденный файл.

TZPATH может содержать только абсолютные пути, никогда – относительные, независимо от способа настройки.

Объект, на который указывает zoneinfo.TZPATH, может измениться при вызове reset_tzpath(), поэтому рекомендуется использовать zoneinfo.TZPATH, а не импортировать TZPATH из zoneinfo или присваивать zoneinfo.TZPATH долгоживущей переменной.

Для получения дополнительной информации о настройке пути поиска временной зоны см. Настройка источников данных.

Исключения и предупреждения¶Exceptions and warnings

exception zoneinfo.ZoneInfoNotFoundError¶

Возникает, когда создание объекта ZoneInfo завершается неудачей, так как указанный ключ не найден в системе. Это подкласс KeyError.

exception zoneinfo.InvalidTZPathWarning¶

Возникает, когда PYTHONTZPATH содержит недопустимый компонент, который будет отфильтрован, например, относительный путь.