`zoneinfo.md`

266 строк · 27.1 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.16/library/zoneinfo.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `zoneinfo` – поддержка часовых поясов IANA89Добавлено в версии 3.9.1011**Исходный код:** [Lib/zoneinfo](https://python-all.ru/3.16/library/zoneinfo.html)1213---1415Модуль `zoneinfo` предоставляет конкретную реализацию часового пояса для поддержки базы данных часовых поясов IANA, изначально описанной в [**PEP 615**](https://python-all.ru/3.16/library/zoneinfo.html). По умолчанию `zoneinfo` использует системные данные о часовых поясах, если они доступны; если системные данные недоступны, библиотека использует собственный пакет [tzdata](https://python-all.ru/3.16/library/zoneinfo.html), доступный на PyPI.1617> **См. также**18>19> **Модуль: [`datetime`](https://python-all.ru/3.16/library/datetime.html#module-datetime)**20>21> Предоставляет типы [`time`](https://python-all.ru/3.16/library/datetime.html#datetime.time) и [`datetime`](https://python-all.ru/3.16/library/datetime.html#datetime.datetime), для использования с которыми предназначен класс [`ZoneInfo`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.ZoneInfo).22>23> **Пакет [tzdata](https://python-all.ru/3.16/library/zoneinfo.html)**24>25> Пакет, поддерживаемый основными разработчиками CPython, для поставки данных о часовых поясах через PyPI.2627[Доступность](https://python-all.ru/3.16/library/intro.html#availability): не WASI.2829Этот модуль не работает или недоступен на WebAssembly. Подробнее см. [платформы WebAssembly](https://python-all.ru/3.16/library/intro.html#wasm-availability).3031## Использование `ZoneInfo`3233[`ZoneInfo`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.ZoneInfo) – это конкретная реализация абстрактного базового класса [`datetime.tzinfo`](https://python-all.ru/3.16/library/datetime.html#datetime.tzinfo), предназначенная для прикрепления к `tzinfo` через конструктор, метод [`datetime.replace`](https://python-all.ru/3.16/library/datetime.html#datetime.datetime.replace) или [`datetime.astimezone`](https://python-all.ru/3.16/library/datetime.html#datetime.datetime.astimezone):3435```python36>>> from zoneinfo import ZoneInfo37>>> import datetime as dt3839>>> when = dt.datetime(2020, 10, 31, 12, tzinfo=ZoneInfo("America/Los_Angeles"))40>>> print(when)412020-10-31 12:00:00-07:004243>>> when.tzname()44'PDT'45```4647Объекты datetime, созданные таким образом, совместимы с арифметикой datetime и обрабатывают переходы на летнее время без дополнительных действий:4849```python50>>> when_add = when + dt.timedelta(days=1)5152>>> print(when_add)532020-11-01 12:00:00-08:005455>>> when_add.tzname()56'PST'57```5859Эти часовые пояса также поддерживают атрибут [`fold`](https://python-all.ru/3.16/library/datetime.html#datetime.datetime.fold), введённый в [**PEP 495**](https://python-all.ru/3.16/library/zoneinfo.html). При переходах смещения, вызывающих неоднозначное время (например, переход с летнего на стандартное время), смещение *до* перехода используется, когда `fold=0`, а смещение *после* перехода используется, когда `fold=1`, например:6061```python62>>> when = dt.datetime(2020, 11, 1, 1, tzinfo=ZoneInfo("America/Los_Angeles"))63>>> print(when)642020-11-01 01:00:00-07:006566>>> print(when.replace(fold=1))672020-11-01 01:00:00-08:0068```6970При преобразовании из другого часового пояса атрибут fold будет установлен в правильное значение:7172```python73>>> LOS_ANGELES = ZoneInfo("America/Los_Angeles")74>>> when_utc = dt.datetime(2020, 11, 1, 8, tzinfo=dt.timezone.utc)7576>>> # Перед переходом с PDT на PST77>>> print(when_utc.astimezone(LOS_ANGELES))782020-11-01 01:00:00-07:007980>>> # После перехода с PDT на PST81>>> print((when_utc + dt.timedelta(hours=1)).astimezone(LOS_ANGELES))822020-11-01 01:00:00-08:0083```8485## Источники данных8687Модуль `zoneinfo` не предоставляет данные о часовых поясах напрямую, а получает информацию о часовых поясах из системной базы данных часовых поясов или из основного пакета PyPI [tzdata](https://python-all.ru/3.16/library/zoneinfo.html), если он доступен. Некоторые системы, в частности Windows, не имеют базы данных IANA, поэтому для проектов, нацеленных на кроссплатформенную совместимость и требующих данные о часовых поясах, рекомендуется объявить зависимость от tzdata. Если ни системные данные, ни tzdata недоступны, все вызовы [`ZoneInfo`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.ZoneInfo) будут вызывать [`ZoneInfoNotFoundError`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.ZoneInfoNotFoundError).8889### Настройка источников данных9091При вызове `ZoneInfo(key)` конструктор сначала ищет в каталогах, указанных в [`TZPATH`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.TZPATH), файл, соответствующий `key`, а в случае неудачи ищет совпадение в пакете tzdata. Это поведение можно настроить тремя способами:92931. Значение [`TZPATH`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.TZPATH) по умолчанию, если не указано иное, можно настроить [на этапе компиляции](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo-data-compile-time-config).942. [`TZPATH`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.TZPATH) можно настроить с помощью [переменной окружения](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo-data-environment-var).953. [Во время выполнения](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo-data-runtime-config) путь поиска можно изменить с помощью функции [`reset_tzpath()`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.reset_tzpath).9697#### Настройка на этапе компиляции9899Путь [`TZPATH`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.TZPATH) по умолчанию включает несколько стандартных мест развёртывания базы данных часовых поясов (кроме Windows, где нет «общеизвестных» мест для данных часовых поясов). В системах POSIX дистрибьюторы и те, кто собирает Python из исходного кода и знает, где развёрнуты системные данные о часовых поясах, могут изменить путь по умолчанию, указав опцию компиляции `TZPATH` (или, что более вероятно, [`configure flag --with-tzpath`](https://python-all.ru/3.16/using/configure.html#cmdoption-with-tzpath)), которая должна быть строкой, разделённой [`os.pathsep`](https://python-all.ru/3.16/library/os.html#os.pathsep).100101На всех платформах настроенное значение доступно как ключ `TZPATH` в [`sysconfig.get_config_var()`](https://python-all.ru/3.16/library/sysconfig.html#sysconfig.get_config_var).102103#### Настройка через переменные окружения104105При инициализации [`TZPATH`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.TZPATH) (либо во время импорта, либо при вызове [`reset_tzpath()`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.reset_tzpath) без аргументов) модуль `zoneinfo` будет использовать переменную окружения `PYTHONTZPATH`, если она существует, для установки пути поиска.106107#### `PYTHONTZPATH`108109Это строка, разделённая [`os.pathsep`](https://python-all.ru/3.16/library/os.html#os.pathsep), содержащая путь поиска часовых поясов. Она должна состоять только из абсолютных, а не относительных путей. Относительные компоненты, указанные в `PYTHONTZPATH`, использоваться не будут, но в остальном поведение при указании относительного пути определяется реализацией; CPython вызовет [`InvalidTZPathWarning`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.InvalidTZPathWarning), но другие реализации могут молча игнорировать ошибочный компонент или вызывать исключение.110111Чтобы настроить систему на игнорирование системных данных и использование пакета tzdata, установите `PYTHONTZPATH=""`.112113#### Настройка во время выполнения114115Путь поиска TZ также можно настроить во время выполнения с помощью функции [`reset_tzpath()`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.reset_tzpath). Обычно это не рекомендуется, но вполне разумно использовать в тестовых функциях, требующих определённого пути к часовым поясам (или отключения доступа к системным часовым поясам).116117## Класс `ZoneInfo`118119#### `class zoneinfo.ZoneInfo(key)`120121Конкретный подкласс [`datetime.tzinfo`](https://python-all.ru/3.16/library/datetime.html#datetime.tzinfo), представляющий часовой пояс IANA, заданный строкой `key`. Вызовы основного конструктора всегда будут возвращать объекты, которые сравниваются идентично; иными словами, если не происходит инвалидации кэша через [`ZoneInfo.clear_cache()`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.ZoneInfo.clear_cache), для всех значений `key` следующее утверждение всегда будет истинным:122123```python124a = ZoneInfo(key)125b = ZoneInfo(key)126assert a is b127```128129`key` должен быть в виде относительного нормализованного пути POSIX, без ссылок на родительские каталоги. Конструктор вызовет [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError), если будет передан несоответствующий ключ.130131Если файл, соответствующий `key`, не найден, конструктор вызовет [`ZoneInfoNotFoundError`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.ZoneInfoNotFoundError).132133Класс `ZoneInfo` имеет два альтернативных конструктора:134135#### `classmethod ZoneInfo.from_file(file_obj, /, key=None)`136137Создаёт объект `ZoneInfo` из файлоподобного объекта, возвращающего байты (например, файл, открытый в бинарном режиме, или объект [`io.BytesIO`](https://python-all.ru/3.16/library/io.html#io.BytesIO)). В отличие от основного конструктора, этот всегда создаёт новый объект.138139Параметр `key` задаёт имя зоны для целей [`__str__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__str__) и [`__repr__()`](https://python-all.ru/3.16/reference/datamodel.html#object.__repr__).140141Объекты, созданные через этот конструктор, не могут быть pickled (см. [pickling](https://python-all.ru/3.16/library/zoneinfo.html#pickling)).142143[`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError) возбуждается, если данные, прочитанные из *file\_obj*, не являются допустимым файлом TZif.144145#### `classmethod ZoneInfo.no_cache(key)`146147Альтернативный конструктор, который обходит кеш конструктора. Он идентичен основному конструктору, но возвращает новый объект при каждом вызове. Это скорее всего будет полезно для целей тестирования или демонстрации, но также может использоваться для создания системы с другой стратегией инвалидации кеша.148149Объекты, созданные через этот конструктор, также будут обходить кеш процесса десериализации при десериализации (unpickled).150151> **Внимание**152>153> Использование этого конструктора может неожиданным образом изменить семантику объектов datetime, используйте его только в том случае, если уверены, что это необходимо.154155Также доступны следующие методы класса:156157#### `classmethod ZoneInfo.clear_cache(*, only_keys=None)`158159Метод для инвалидации кеша класса `ZoneInfo`. Если аргументы не переданы, все кеши инвалидируются, и следующий вызов основного конструктора для каждого ключа вернёт новый экземпляр.160161Если в параметр `only_keys` передан итерируемый объект с именами ключей, из кеша будут удалены только указанные ключи. Ключи, переданные в `only_keys`, но не найденные в кеше, игнорируются.162163> **Предупреждение**164>165> Вызов этой функции может неожиданным образом изменить семантику объектов datetime, использующих `ZoneInfo`; это изменяет состояние модуля и, таким образом, может иметь широкий спектр последствий. Используйте её, только если уверены, что это необходимо.166167Класс имеет один атрибут:168169#### `ZoneInfo.key`170171Это [атрибут](https://python-all.ru/3.16/glossary.html#term-attribute) только для чтения, который возвращает значение `key`, переданное конструктору; это должен быть ключ поиска в базе данных часовых поясов IANA (например, `America/New_York`, `Europe/Paris` или `Asia/Tokyo`).172173Для зон, созданных из файла без указания параметра `key`, этому атрибуту будет присвоено значение `None`.174175> **Примечание**176>177> Хотя существует довольно распространённая практика показывать эти значения конечным пользователям, они предназначены для использования в качестве первичных ключей для представления соответствующих зон и не обязательно являются элементами пользовательского интерфейса. Такие проекты, как CLDR (Unicode Common Locale Data Repository), можно использовать для получения более удобных для пользователя строк из этих ключей.178179### Строковые представления180181Строковое представление, возвращаемое при вызове [`str`](https://python-all.ru/3.16/library/stdtypes.html#str) для объекта [`ZoneInfo`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.ZoneInfo), по умолчанию использует атрибут [`ZoneInfo.key`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.ZoneInfo.key) (см. примечание об использовании в документации атрибута):182183```python184>>> zone = ZoneInfo("Pacific/Kwajalein")185>>> str(zone)186'Pacific/Kwajalein'187188>>> when = dt.datetime(2020, 4, 1, 3, 15, tzinfo=zone)189>>> f"{when.isoformat()} [{when.tzinfo}]"190'2020-04-01T03:15:00+12:00 [Pacific/Kwajalein]'191```192193Для объектов, созданных из файла без указания параметра `key`, `str` прибегает к вызову [`repr()`](https://python-all.ru/3.16/library/functions.html#repr). `repr` объекта `ZoneInfo` определяется реализацией и не обязательно стабилен между версиями, но гарантируется, что он не является допустимым ключом `ZoneInfo`.194195### Сериализация pickle196197Вместо сериализации всех данных переходов объекты `ZoneInfo` сериализуются по ключу, а объекты `ZoneInfo`, созданные из файлов (даже те, для которых указано значение `key`), не могут быть pickled.198199Поведение файла `ZoneInfo` зависит от того, как он был создан:2002011. `ZoneInfo(key)`: При создании через основной конструктор объект `ZoneInfo` сериализуется по ключу, и при десериализации процесс десериализации использует основной конструктор, поэтому ожидается, что это будет тот же объект, что и другие ссылки на тот же часовой пояс. Например, если `europe_berlin_pkl` – это строка, содержащая pickle, созданный из `ZoneInfo("Europe/Berlin")`, можно ожидать следующего поведения:202203   ```pycon204   >>> a = ZoneInfo("Europe/Berlin")205   >>> b = pickle.loads(europe_berlin_pkl)206   >>> a is b207   True208   ```2092. `ZoneInfo.no_cache(key)`: При создании через конструктор, обходящий кеш, объект `ZoneInfo` также сериализуется по ключу, но при десериализации процесс десериализации использует конструктор, обходящий кеш. Если `europe_berlin_pkl_nc` – это строка, содержащая pickle, созданный из `ZoneInfo.no_cache("Europe/Berlin")`, можно ожидать следующего поведения:210211   ```pycon212   >>> a = ZoneInfo("Europe/Berlin")213   >>> b = pickle.loads(europe_berlin_pkl_nc)214   >>> a is b215   False216   ```2173. `ZoneInfo.from_file(file_obj, /, key=None)`: При создании из файла объект `ZoneInfo` возбуждает исключение при попытке pickling. Если конечный пользователь хочет pickle объект `ZoneInfo`, созданный из файла, рекомендуется использовать тип-обёртку или пользовательскую функцию сериализации: либо сериализовать по ключу, либо сохранить содержимое файлового объекта и сериализовать его.218219Этот метод сериализации требует, чтобы данные часового пояса для требуемого ключа были доступны и на сериализующей, и на десериализующей стороне – аналогично тому, как ссылки на классы и функции должны существовать в обеих средах: сериализующей и десериализующей. Это также означает, что не даётся никаких гарантий согласованности результатов при десериализации (unpickling) объекта `ZoneInfo`, который был pickled в среде с другой версией данных часового пояса.220221## Функции222223#### `zoneinfo.available_timezones()`224225Возвращает набор, содержащий все допустимые ключи для часовых поясов IANA, доступные где-либо в пути часовых поясов. Это значение пересчитывается при каждом вызове функции.226227Эта функция включает только канонические имена зон и не включает «особые» зоны, такие как те, что находятся в каталогах `posix/` и `right/`, зону `posixrules` или зону `localtime`.228229> **Внимание**230>231> Эта функция может открывать большое количество файлов, так как лучший способ определить, является ли файл в пути временной зоны допустимой временной зоной, – прочитать «магическую строку» в начале.232233> **Примечание**234>235> Эти значения не предназначены для отображения конечным пользователям; для элементов пользовательского интерфейса приложениям следует использовать что-то вроде CLDR (Общего репозитория локалей Unicode), чтобы получить более удобочитаемые строки. См. также предостережение по [`ZoneInfo.key`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.ZoneInfo.key).236237#### `zoneinfo.reset_tzpath(to=None)`238239Устанавливает или сбрасывает путь поиска временной зоны ([`TZPATH`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.TZPATH)) для модуля. При вызове без аргументов `TZPATH` устанавливается в значение по умолчанию.240241Вызов `reset_tzpath` не сбросит кеш [`ZoneInfo`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.ZoneInfo), поэтому вызовы конструктора `ZoneInfo` будут использовать новый `TZPATH` только в случае промаха кеша.242243Параметр `to` должен быть [последовательностью](https://python-all.ru/3.16/glossary.html#term-sequence) строк или [`os.PathLike`](https://python-all.ru/3.16/library/os.html#os.PathLike), а не строкой, причём все элементы должны быть абсолютными путями. Будет вызвано исключение [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError), если передан не абсолютный путь.244245## Глобальные переменные246247#### `zoneinfo.TZPATH`248249Последовательность только для чтения, представляющая путь поиска временной зоны: при создании `ZoneInfo` по ключу ключ объединяется с каждым элементом в `TZPATH`, и используется первый найденный файл.250251`TZPATH` может содержать только абсолютные пути, никогда – относительные, независимо от способа настройки.252253Объект, на который указывает `zoneinfo.TZPATH`, может измениться при вызове [`reset_tzpath()`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.reset_tzpath), поэтому рекомендуется использовать `zoneinfo.TZPATH`, а не импортировать `TZPATH` из `zoneinfo` или присваивать `zoneinfo.TZPATH` долгоживущей переменной.254255Для получения дополнительной информации о настройке пути поиска временной зоны см. [Настройка источников данных](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo-data-configuration).256257## Исключения и предупреждения258259#### `exception zoneinfo.ZoneInfoNotFoundError`260261Возникает, когда создание объекта [`ZoneInfo`](https://python-all.ru/3.16/library/zoneinfo.html#zoneinfo.ZoneInfo) завершается неудачей, так как указанный ключ не найден в системе. Это подкласс [`KeyError`](https://python-all.ru/3.16/library/exceptions.html#KeyError).262263#### `exception zoneinfo.InvalidTZPathWarning`264265Возникает, когда [`PYTHONTZPATH`](https://python-all.ru/3.16/library/zoneinfo.html#envvar-PYTHONTZPATH) содержит недопустимый компонент, который будет отфильтрован, например, относительный путь.266