# `zoneinfo` — Prise en charge des fuseaux horaires IANA

Nouveau dans la version 3.9.

Code source : Lib/zoneinfo

Le module `zoneinfo` fournit une implémentation concrète des fuseaux horaires qui s'appuie sur la base de données de fuseaux horaires IANA spécifiée initialement dans la PEP 615. Par défaut, `zoneinfo` utilise les données des fuseaux horaires du système si elles sont disponibles, sinon la bibliothèque utilise le paquet quasi natif tzdata disponible sur PyPI.

Voir aussi

Module : `datetime`

  Fournit les types `time` et `datetime` attendus par `ZoneInfo`.

Paquet tzdata

  Paquet « quasi natif » maintenu par les développeurs de CPython pour fournir les données des fuseaux horaires via PyPI.

Disponibilité : pas Emscripten, pas WASI.

Ce module ne fonctionne pas ou n’est pas disponible sur les plateformes WebAssembly `wasm32-emscripten` et `wasm32-wasi`. Voir Plateformes WebAssembly pour plus d’informations.

## Utilisation de `ZoneInfo`

`ZoneInfo` est une implémentation concrète de la classe de base abstraite `datetime.tzinfo` et est destinée à être rattachée à `tzinfo`, par le constructeur, par `datetime.replace` ou par `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'

Les datetime construits de cette manière sont compatibles avec l'arithmétique datetime et gèrent le passage à l'heure d'été sans autre intervention :

    >>> dt_add = dt + timedelta(days=1)

    >>> print(dt_add)
    2020-11-01 12:00:00-08:00

    >>> dt_add.tzname()
    'PST'

Ces fuseaux horaires prennent aussi en charge l'attribut `fold` introduit dans la PEP 495. Pendant les transitions des décalages horaires qui induisent des temps ambigus (comme le passage de l'heure d'été à l'heure normale), le décalage avant la transition est utilisé quand `fold=0`, et le décalage après la transition est utilisé quand `fold=1`, par exemple :

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

Lors de la conversion à partir d'un autre fuseau horaire, fold est réglé à la valeur correcte :

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

## Sources de données

Le module `zoneinfo` ne fournit pas de données de fuseaux horaires directement, mais extrait des informations sur les fuseaux horaires de la base de données des fuseaux horaires du système ou du paquet PyPI quasi natif tzdata, s'ils sont disponibles. Certains systèmes, comme les systèmes Windows, n'ont pas de base de données IANA, il est donc recommandé aux projets visant la compatibilité entre plates-formes et qui nécessitent des données sur les fuseaux horaires, de déclarer une dépendance à tzdata. Si aucune donnée système, ni tzdata, n'est disponible, tous les appels à `ZoneInfo` lèvent `ZoneInfoNotFoundError`.

### Configurer les sources de données

Lorsque `ZoneInfo(key)` est appelé, le constructeur recherche d'abord un fichier nommé `key` dans les répertoires spécifiés par `TZPATH` et, en cas d'échec, recherche dans le paquet tzdata. Ce comportement peut être configuré de trois manières :

1. La valeur par défaut `TZPATH`, lorsqu'elle n'est pas spécifiée autrement, peut être configurée à la compilation.

2. `TZPATH` peut être configuré en utilisant une variable d'environnement.

3. À l'exécution, le chemin de recherche peut être manipulé à l'aide de la fonction `reset_tzpath()`.

#### Configuration à la compilation

Par défaut, `TZPATH` indique plusieurs emplacements de déploiement courants pour la base de données de fuseaux horaires (sauf sous Windows, où il n'existe pas de consensus pour l'emplacement des données de fuseaux horaires). Sur les systèmes POSIX, les distributeurs en aval ainsi que ceux qui construisent Python à partir des sources et qui savent où sont déployées les données de fuseau horaire de leur système peuvent modifier le chemin par défaut en spécifiant l'option de compilation `TZPATH` (ou, plus probablement, en utilisant l'option `--with-tzpath` du script `configure`), qui doit être une chaîne délimitée par `os.pathsep`.

Sur toutes les plates-formes, la valeur configurée est disponible en tant que clé de `TZPATH` dans `sysconfig.get_config_var()`.

#### Configuration par l'environnement

Lors de l'initialisation de `TZPATH` (soit au moment de l'importation, soit lorsque `reset_tzpath()` est appelé sans argument), le module `zoneinfo` utilise la variable d'environnement `PYTHONTZPATH`, si elle existe, pour définir le chemin de recherche.

PYTHONTZPATH

  Il s'agit d'une chaîne séparée par `os.pathsep` contenant le chemin de recherche du fuseau horaire à utiliser. Elle doit être constituée uniquement de chemins absolus et non de chemins relatifs. Les composants relatifs spécifiés dans `PYTHONTZPATH` ne sont pas utilisés, mais le comportement reste défini par l'implémentation lorsqu'un chemin relatif est spécifié. CPython lève `InvalidTZPathWarning` dans ce cas. Les autres implémentations sont libres d'ignorer silencieusement le composant erroné ou de lever une exception.

Pour que le système ignore les données système et utilise le paquet tzdata à la place, définissez `PYTHONTZPATH=""`.

#### Configuration à l'exécution

Le chemin de recherche TZ peut également être configuré au moment de l'exécution à l'aide de la fonction `reset_tzpath()`. Cette opération n'est généralement pas conseillée, bien qu'il soit raisonnable de l'utiliser dans les fonctions de test qui nécessitent l'utilisation d'un chemin de fuseau horaire spécifique (ou qui nécessitent de désactiver l'accès aux fuseaux horaires du système).

## La classe `ZoneInfo`

class zoneinfo.ZoneInfo(key)

  Une sous-classe concrète de `datetime.tzinfo` qui représente un fuseau horaire IANA spécifié par la chaîne `key`. Les appels au constructeur principal renvoient toujours des objets dont la comparaison est identique ; autrement dit, sauf invalidation du cache via `ZoneInfo.clear_cache()`, pour toutes les valeurs de `key`, l'assertion suivante est toujours vraie :

      a = ZoneInfo(key)
      b = ZoneInfo(key)
      assert a is b

  `key` doit être sous la forme d'un chemin POSIX relatif et normalisé, sans références de niveau supérieur. Le constructeur lève `ValueError` si une clé non conforme est passée.

  Si aucun fichier correspondant à `key` n'est trouvé, le constructeur lève `ZoneInfoNotFoundError`.

La classe `ZoneInfo` possède deux constructeurs alternatifs :

classmethod ZoneInfo.from_file(fobj, /, key=None)

  Construit un objet `ZoneInfo` à partir d'un objet fichier renvoyant des octets (par exemple, un fichier ouvert en mode binaire ou un objet `io.BytesIO`). Contrairement au constructeur principal, il construit toujours un nouvel objet.

  Le paramètre `key` définit le nom de la zone pour les besoins de `__str__()` et `__repr__()`.

  Les objets créés via ce constructeur ne peuvent pas être sérialisés (voir pickling).

classmethod ZoneInfo.no_cache(key)

  Un constructeur alternatif qui contourne le cache du constructeur. Il est identique au constructeur principal, mais renvoie un nouvel objet à chaque appel. Il est surtout utile à des fins de test ou de démonstration, mais il peut également être utilisé pour créer un système avec une stratégie d'invalidation du cache différente.

  Les objets créés via ce constructeur contournent également le cache d'un processus de désérialisation lorsqu'ils sont désérialisés.

  Prudence

  L'utilisation de ce constructeur peut modifier la sémantique de vos datetimes de manière surprenante, ne l'utilisez que si vous en avez vraiment besoin.

Les méthodes de classe suivantes sont également disponibles :

classmethod ZoneInfo.clear_cache(*, only_keys=None)

  Une méthode pour invalider le cache de la classe `ZoneInfo`. Si aucun argument n'est passé, tous les caches sont invalidés et le prochain appel au constructeur principal pour chaque clé renverra une nouvelle instance.

  Si un itérable de noms de clés est passé au paramètre `only_keys`, seules les clés spécifiées sont retirées du cache. Les clés passées à `only_keys` mais non trouvées dans le cache sont ignorées.

  Avertissement

  L'invocation de cette fonction peut changer la sémantique des datetimes utilisant `ZoneInfo` de manière surprenante ; cela modifie l'état global du processus et peut donc avoir des effets étendus. Ne l'utilisez que si vous en avez vraiment besoin.

La classe a un attribut :

ZoneInfo.key

  Il s'agit d'un attribut en lecture seule qui renvoie la valeur de `key` passée au constructeur, qui doit être une clé de recherche dans la base de données des fuseaux horaires de l'IANA (par exemple, `America/New_York`, `Europe/Paris` ou `Asia/Tokyo`).

  Pour les zones construites à partir d'un fichier sans spécifier de paramètre `key`, cette valeur sera fixée à `None`.

  Note

  Bien qu'il soit assez courant de les exposer aux utilisateurs finaux, ces valeurs sont conçues pour être des clés primaires permettant de représenter les zones concernées et pas nécessairement des éléments destinés à l'utilisateur. Des projets comme CLDR (Unicode Common Locale Data Repository) peuvent être utilisés pour obtenir des chaînes de caractères plus conviviales à partir de ces clés.

### Représentation sous forme de chaîne de caractères

La représentation sous forme de chaîne renvoyée lors de l’appel de `str` sur un objet `ZoneInfo` utilise par défaut l’attribut `ZoneInfo.key` (voir la note sur l’utilisation dans la documentation de l’attribut) :

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

Pour les objets construits à partir d’un fichier sans spécifier de paramètre `key`, `str` revient à appeler `repr()`. Le `repr` de `ZoneInfo` est défini par l’implémentation et n’est pas nécessairement stable entre les versions, mais il est garanti qu’il ne fournit pas un paramètre key `ZoneInfo` valide.

### Sérialisation Pickle

Plutôt que de sérialiser toutes les données de transition, les objets `ZoneInfo` sont sérialisés à partir de l'attribut key et les objets `ZoneInfo` construits à partir de fichiers (même ceux avec une valeur pour `key` spécifiée) ne peuvent pas être sérialisés.

Le comportement d’un fichier `ZoneInfo` dépend de la façon dont il a été construit :

1. `ZoneInfo(key)` : lorsqu’il est construit avec le constructeur primaire, un objet `ZoneInfo` est sérialisé en utilisant l'attribut key et, lorsqu’il est désérialisé, le processus de désérialisation utilise le constructeur primaire et donc on s’attend à ce qu’il soit le même objet que d’autres références au même fuseau horaire. Par exemple, si `europe_berlin_pkl` est une chaîne contenant un objet sérialisé construit à partir de `ZoneInfo("Europe/Berlin")`, on s’attend au comportement suivant :

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

2. `ZoneInfo.no_cache(key)` : lorsqu’il est construit à partir du constructeur de contournement de cache, l’objet `ZoneInfo` est également sérialisé en utilisant l'attribut key mais, lorsqu’il est désérialisé, le processus de désérialisation utilise le constructeur de contournement de cache. Si `europe_berlin_pkl_nc` est une chaîne contenant un objet sérialisé construit à partir de `ZoneInfo.no_cache("Europe/Berlin")`, le comportement suivant est attendu :

       >>> a = ZoneInfo("Europe/Berlin")
       >>> b = pickle.loads(europe_berlin_pkl_nc)
       >>> a is b
       False

3. `ZoneInfo.from_file(fobj, /, key=None)` : lorsqu’il est construit à partir d’un fichier, l’objet `ZoneInfo` lève une exception lors de la sérialisation. Si un utilisateur souhaite récupérer une `ZoneInfo` construite à partir d’un fichier, il est recommandé d’encapsuler les données dans un autre type ou d’utiliser une fonction de sérialisation personnalisée : soit en sérialisant en utilisant l'attribut key, soit en stockant le contenu de l’objet fichier et en sérialisant cet objet.

Cette méthode de sérialisation nécessite que les données de fuseau horaire relatives à l'attribut key soient disponibles à la fois du côté de la sérialisation et de la désérialisation, de la même manière que les références aux classes et aux fonctions sont censées exister dans les environnements de sérialisation et de désérialisation. Cela signifie également qu’aucune garantie n’est donnée quant à la cohérence des résultats lors de la désérialisation d’un `ZoneInfo` sérialisé dans un environnement avec une version différente des données de fuseau horaire.

## Fonctions

zoneinfo.available_timezones()

  Fournit un ensemble contenant toutes les clés valides pour les fuseaux horaires IANA disponibles n’importe où sur TZPATH. Il est recalculé à chaque appel à la fonction.

  Cette fonction n’inclut que les noms de zone canoniques et n’inclut pas les zones « spéciales » telles que celles sous les répertoires `posix/` et `right/`, ou la zone `posixrules`.

  Prudence

  cette fonction peut ouvrir un grand nombre de fichiers, car la meilleure façon de déterminer si un fichier sur le chemin du fuseau horaire est un fuseau horaire valide est de lire la « chaîne magique » au début.

  Note

  ces valeurs n’ont pas vocation à être montrées aux utilisateurs ; pour les éléments destinés à l’utilisateur, les applications doivent utiliser quelque chose comme CLDR (le référentiel de données Unicode Common Locale) afin d’obtenir des chaînes plus conviviales. Voir aussi la note d’avertissement sur `ZoneInfo.key`.

zoneinfo.reset_tzpath(to=None)

  Définit ou réinitialise le chemin de recherche des fuseaux horaires (`TZPATH`) pour le module. Lorsqu’il est appelé sans arguments, `TZPATH` est défini sur la valeur par défaut.

  Appeler `reset_tzpath` n’invalide pas le cache `ZoneInfo`, donc les appels au constructeur primaire `ZoneInfo` n’utiliseront le nouveau `TZPATH` qu’en cas d’échec du cache.

  Le paramètre `to` doit être une séquence de chaînes ou `os.PathLike` et non une chaîne, qui doivent toutes être des chemins absolus. `ValueError` est levée si autre chose qu’un chemin absolu est passé.

## Variables globales

zoneinfo.TZPATH

  Séquence en lecture seule représentant le chemin de recherche des fuseaux horaires – lors de la construction d’un `ZoneInfo` à partir de l'attribut key, la clé est jointe à chaque entrée dans le `TZPATH` et le premier fichier trouvé est utilisé.

  `TZPATH` ne peut contenir que des chemins absolus, jamais des chemins relatifs, quelle que soit sa configuration.

  L’objet vers lequel `zoneinfo.TZPATH` pointe peut changer suite à un appel à `reset_tzpath()`, il est donc recommandé d’utiliser `zoneinfo.TZPATH` plutôt que d’importer `TZPATH` de `zoneinfo` ou en assignant une variable de longue durée à `zoneinfo.TZPATH`.

  Pour plus d’informations sur la configuration du chemin de recherche des fuseaux horaires, consultez Configurer les sources de données.

## Exceptions et avertissements

exception zoneinfo.ZoneInfoNotFoundError

  Levée lorsque la construction d’un objet `ZoneInfo` échoue parce que la clé spécifiée est introuvable sur le système. C’est une sous-classe de `KeyError`.

exception zoneinfo.InvalidTZPathWarning

  Levée lorsque `PYTHONTZPATH` contient un composant non valide qui ne sera pas retenu, tel qu’un chemin relatif.