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