zoneinfo
— IANA time zone support¶
Added in version 3.9.
Source code: Lib/zoneinfo
The zoneinfo
module provides a concrete time zone implementation to
support the IANA time zone database as originally specified in PEP 615. By
default, zoneinfo
uses the system’s time zone data if available; if no
system time zone data is available, the library will fall back to using the
first-party tzdata package available on PyPI.
Дивись також
Availability: not WASI.
This module does not work or is not available on WebAssembly. See WebAssembly platforms for more information.
Використання 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
Під час конвертації з іншого часового поясу для згортки буде встановлено правильне значення:
>>> 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
Джерела даних¶
The zoneinfo
module does not directly provide time zone data, and instead
pulls time zone information from the system time zone database or the
first-party PyPI package tzdata, if available. Some systems, including
notably Windows systems, do not have an IANA database available, and so for
projects targeting cross-platform compatibility that require time zone data, it
is recommended to declare a dependency on tzdata. If neither system data nor
tzdata are available, all calls to ZoneInfo
will raise
ZoneInfoNotFoundError
.
Налаштування джерел даних¶
Коли викликається ZoneInfo(key)
, конструктор спочатку шукає файл, який відповідає key
, у каталогах, указаних у TZPATH
, а в разі помилки шукає відповідність у пакеті tzdata. Цю поведінку можна налаштувати трьома способами:
Типовий
TZPATH
, якщо не вказано інше, можна налаштувати під час компіляції.TZPATH
можна налаштувати за допомогою змінної середовища.У runtime шляхом пошуку можна маніпулювати за допомогою функції
reset_tzpath()
.
Конфігурація під час компіляції¶
За замовчуванням TZPATH
містить кілька поширених місць розгортання бази даних часових поясів (за винятком Windows, де немає «добре відомих» місць для даних часових поясів). У системах POSIX розповсюджувачі нижньої течії та ті, хто створює Python із джерела, які знають, де розгортаються дані часових поясів у їхній системі, можуть змінити шлях часового поясу за замовчуванням, вказавши параметр під час компіляції TZPATH
(або, що ймовірніше, параметр configure flag --with-tzpath
), який має бути рядком, розділеним os.pathsep
.
На всіх платформах налаштоване значення доступне як ключ TZPATH
у sysconfig.get_config_var()
.
Конфігурація середовища¶
Під час ініціалізації TZPATH
(або під час імпортування, або коли reset_tzpath()
викликається без аргументів), модуль zoneinfo
використовуватиме змінну середовища PYTHONTZPATH
, якщо вона існує, щоб встановити шлях пошуку.
- PYTHONTZPATH¶
Це розділений
os.pathsep
рядок, який містить шлях пошуку часового поясу, який слід використовувати. Він має складатися лише з абсолютних, а не відносних шляхів. Відносні компоненти, указані вPYTHONTZPATH
, не використовуватимуться, але в інших випадках поведінка, коли вказано відносний шлях, визначається реалізацією; CPython викличеInvalidTZPathWarning
, але інші реалізації можуть мовчки ігнорувати помилковий компонент або викликати виняток.
Щоб налаштувати систему на ігнорування системних даних і використання замість них пакета tzdata, установіть PYTHONTZPATH=""
.
Конфігурація середовища виконання¶
Шлях пошуку TZ також можна налаштувати під час виконання за допомогою функції reset_tzpath()
. Зазвичай це не рекомендована операція, хоча її доцільно використовувати в тестових функціях, які вимагають використання певного шляху часового поясу (або вимагають вимкнення доступу до часових поясів системи).
Клас 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
, якщо передано невідповідний ключ.Якщо не знайдено жодного файлу, що відповідає
ключу
, конструктор викличеZoneInfoNotFoundError
.
Клас ZoneInfo
має два альтернативних конструктори:
- classmethod ZoneInfo.from_file(fobj, /, key=None)¶
Створює об’єкт
ZoneInfo
з файлоподібного об’єкта, який повертає байти (наприклад, файл, відкритий у двійковому режимі, або об’єктio.BytesIO
). На відміну від первинного конструктора, це завжди створює новий об’єкт.Параметр
key
встановлює назву зони для цілей__str__()
і__repr__()
.Об’єкти, створені за допомогою цього конструктора, не можуть бути протравлені (див. pickling).
- classmethod ZoneInfo.no_cache(key)¶
Альтернативний конструктор, який обходить кеш конструктора. Він ідентичний основному конструктору, але повертає новий об’єкт під час кожного виклику. Це, швидше за все, буде корисним для тестування чи демонстрації, але його також можна використовувати для створення системи з іншою стратегією анулювання кешу.
Об’єкти, створені за допомогою цього конструктора, також обійдуть кеш процесу десеріалізації, коли їх не буде вибрано.
Застереження
Використання цього конструктора може дивовижним чином змінити семантику ваших дат і часів, використовуйте його, лише якщо ви знаєте, що вам це потрібно.
Також доступні такі методи класу:
- classmethod ZoneInfo.clear_cache(*, only_keys=None)¶
Метод анулювання кешу в класі
ZoneInfo
. Якщо аргументи не передано, усі кеші стають недійсними, а наступний виклик основного конструктора для кожного ключа поверне новий екземпляр.Якщо в параметр
only_keys
передається ітерація імен ключів, з кешу буде видалено лише вказані ключі. Ключі, передані вonly_keys
, але не знайдені в кеші, ігноруються.Попередження
Invoking this function may change the semantics of datetimes using
ZoneInfo
in surprising ways; this modifies module state and thus may have wide-ranging effects. Only use it if you know that you need to.
Клас має один атрибут:
- ZoneInfo.key¶
Це лише для читання attribute, який повертає значення
key
, переданого конструктору, який має бути ключем пошуку в базі даних часового поясу IANA (наприклад,America/New_York
,Європа/Париж
абоАзія/Токіо
).Для зон, створених із файлу без зазначення параметра
key
, буде встановленоNone
.Примітка
Хоча надавати їх кінцевим користувачам є досить поширеною практикою, ці значення призначені як первинні ключі для представлення відповідних зон, а не обов’язково для елементів, спрямованих на користувача. Такі проекти, як CLDR (загальне сховище даних Unicode Common Locale Data Repository), можна використовувати для отримання більш зручних рядків із цих ключів.
Рядкові представлення¶
Рядкове представлення, що повертається під час виклику str
для об’єкта ZoneInfo
, за замовчуванням використовує атрибут ZoneInfo.key
(див. примітку щодо використання в документації атрибута):
>>> 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]'
Для об’єктів, створених із файлу без вказівки параметра key
, str
повертається до виклику repr()
. Repr
ZoneInfo
визначається реалізацією і не обов’язково є стабільним між версіями, але гарантовано, що він не є дійсним ключем ZoneInfo
.
Серіалізація соління¶
Замість того, щоб серіалізувати всі дані переходу, об’єкти ZoneInfo
серіалізуються за ключем, а об’єкти ZoneInfo
, створені з файлів (навіть ті, у яких указано значення key
), не можуть бути мариновані.
Поведінка файлу ZoneInfo
залежить від того, як він був створений:
ZoneInfo(key)
: коли створюється за допомогою первинного конструктора, об’єктZoneInfo
серіалізується за ключем, а коли десеріалізується, процес десеріалізації використовує первинний, тому очікується, що вони будуть той самий об’єкт, що й інші посилання на той самий часовий пояс. Наприклад, якщоeurope_berlin_pkl
- це рядок, що містить маринований пікле, створений зZoneInfo("Europe/Berlin")
, можна очікувати такої поведінки:>>> a = ZoneInfo("Europe/Berlin") >>> b = pickle.loads(europe_berlin_pkl) >>> a is b True
ZoneInfo.no_cache(key)
: коли створено з конструктора обходу кешу, об’єктZoneInfo
також серіалізується за ключем, але при десеріалізації процес десеріалізації використовує конструктор обходу кешу. Якщоeurope_berlin_pkl_nc
- це рядок, що містить маринований пікле, побудований зZoneInfo.no_cache("Europe/Berlin")
, можна очікувати такої поведінки:>>> a = ZoneInfo("Europe/Berlin") >>> b = pickle.loads(europe_berlin_pkl_nc) >>> a is b False
ZoneInfo.from_file(fobj, /, key=None)
: коли створено з файлу, об’єктZoneInfo
викликає виключення під час травлення. Якщо кінцевий користувач хоче вибратиZoneInfo
, створений з файлу, рекомендується використовувати тип оболонки або спеціальну функцію серіалізації: або серіалізація за ключем, або збереження вмісту об’єкта файлу та його серіалізація.
Цей метод серіалізації вимагає, щоб дані часового поясу для необхідного ключа були доступні як на стороні серіалізації, так і на стороні десеріалізації, подібно до того, як очікуються посилання на класи та функції в середовищах серіалізації та десеріалізації. Це також означає, що не надається жодних гарантій щодо узгодженості результатів під час видалення ZoneInfo
, вибраного в середовищі з іншою версією даних часового поясу.
Функції¶
- zoneinfo.available_timezones()¶
Отримайте набір, що містить усі дійсні ключі для часових поясів IANA, доступних будь-де на шляху часового поясу. Це перераховується під час кожного виклику функції.
Ця функція включає лише канонічні назви зон і не включає «спеціальні» зони, такі як ті, що знаходяться в каталогах
posix/
іright/
або зонаposixrules
.Застереження
Ця функція може відкрити велику кількість файлів, оскільки найкращий спосіб визначити, чи є файл на шляху до часового поясу дійсним часовим поясом, це прочитати «магічний рядок» на початку.
Примітка
Ці значення не призначені для надання кінцевим користувачам; для елементів, які відкриваються користувачам, програми повинні використовувати щось на зразок CLDR (сховище даних Unicode Common Locale), щоб отримати більш зручні рядки. Дивіться також застереження щодо
ZoneInfo.key
.
- zoneinfo.reset_tzpath(to=None)¶
Встановлює або скидає шлях пошуку часового поясу (
TZPATH
) для модуля. При виклику без аргументівTZPATH
встановлюється на значення за замовчуванням.Виклик
reset_tzpath
не призведе до недійсностіZoneInfo
кешу, тому виклики основногоZoneInfo
конструктора використовуватимуть новийTZPATH
лише у випадку промаху кешу.Параметр
to
має бути sequence рядків або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
містить недійсний компонент, який буде відфільтровано, наприклад відносний шлях.