# `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.

Дивись також

Модуль: `datetime`

  Надає типи `time` і `datetime`, з якими призначений клас `ZoneInfo`.

Package tzdata

  Пакет першої сторони, який підтримується розробниками ядра CPython для надання даних про часовий пояс через 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. Цю поведінку можна налаштувати трьома способами:

1. Типовий `TZPATH`, якщо не вказано інше, можна налаштувати під час компіляції.

2. `TZPATH` можна налаштувати за допомогою змінної середовища.

3. У 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(file_obj, /, 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` залежить від того, як він був створений:

1. `ZoneInfo(key)`: коли створюється за допомогою первинного конструктора, об’єкт `ZoneInfo` серіалізується за ключем, а коли десеріалізується, процес десеріалізації використовує первинний, тому очікується, що вони будуть той самий об’єкт, що й інші посилання на той самий часовий пояс. Наприклад, якщо `europe_berlin_pkl` - це рядок, що містить маринований пікле, створений з `ZoneInfo("Europe/Berlin")`, можна очікувати такої поведінки:

       >>> a = ZoneInfo("Europe/Berlin")
       >>> b = pickle.loads(europe_berlin_pkl)
       >>> a is b
       True

2. `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

3. `ZoneInfo.from_file(file_obj, /, key=None)`: When constructed from a file, the `ZoneInfo` object raises an exception on pickling. If an end user wants to pickle a `ZoneInfo` constructed from a file, it is recommended that they use a wrapper type or a custom serialization function: either serializing by key or storing the contents of the file object and serializing that.

Цей метод серіалізації вимагає, щоб дані часового поясу для необхідного ключа були доступні як на стороні серіалізації, так і на стороні десеріалізації, подібно до того, як очікуються посилання на класи та функції в середовищах серіалізації та десеріалізації. Це також означає, що не надається жодних гарантій щодо узгодженості результатів під час видалення `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` містить недійсний компонент, який буде відфільтровано, наприклад відносний шлях.