"zoneinfo" — Prise en charge des fuseaux horaires IANA
******************************************************

Nouveau dans la version 3.9.

======================================================================

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.


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* sera
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 "zoninfo" 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, et donc il
est 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" comprend 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 et 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 précisément, avec 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
-------------------------------------------------

The string representation returned when calling "str" on a "ZoneInfo"
object defaults to using the "ZoneInfo.key" attribute (see the note on
usage in the attribute documentation):

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

For objects constructed from a file without specifying a "key"
parameter, "str" falls back to calling "repr()". "ZoneInfo"'s "repr"
is implementation-defined and not necessarily stable between versions,
but it is guaranteed not to be a valid "ZoneInfo" key.


Pickle serialization
--------------------

Rather than serializing all transition data, "ZoneInfo" objects are
serialized by key, and "ZoneInfo" objects constructed from files (even
those with a value for "key" specified) cannot be pickled.

The behavior of a "ZoneInfo" file depends on how it was constructed:

1. "ZoneInfo(key)": When constructed with the primary constructor, a
   "ZoneInfo" object is serialized by key, and when deserialized, the
   deserializing process uses the primary and thus it is expected that
   these are expected to be the same object as other references to the
   same time zone.  For example, if "europe_berlin_pkl" is a string
   containing a pickle constructed from "ZoneInfo("Europe/Berlin")",
   one would expect the following behavior:

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

2. "ZoneInfo.no_cache(key)": When constructed from the cache-bypassing
   constructor, the "ZoneInfo" object is also serialized by key, but
   when deserialized, the deserializing process uses the cache
   bypassing constructor. If "europe_berlin_pkl_nc" is a string
   containing a pickle constructed from
   "ZoneInfo.no_cache("Europe/Berlin")", one would expect the
   following behavior:

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

3. "ZoneInfo.from_file(fobj, /, 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.

This method of serialization requires that the time zone data for the
required key be available on both the serializing and deserializing
side, similar to the way that references to classes and functions are
expected to exist in both the serializing and deserializing
environments. It also means that no guarantees are made about the
consistency of results when unpickling a "ZoneInfo" pickled in an
environment with a different version of the time zone data.


Fonctions
=========

zoneinfo.available_timezones()

   Get a set containing all the valid keys for IANA time zones
   available anywhere on the time zone path. This is recalculated on
   every call to the function.

   This function only includes canonical zone names and does not
   include "special" zones such as those under the "posix/" and
   "right/" directories, or the "posixrules" zone.

   Prudence:

     This function may open a large number of files, as the best way
     to determine if a file on the time zone path is a valid time zone
     is to read the "magic string" at the beginning.

   Note:

     These values are not designed to be exposed to end-users; for
     user facing elements, applications should use something like CLDR
     (the Unicode Common Locale Data Repository) to get more user-
     friendly strings. See also the cautionary note on "ZoneInfo.key".

zoneinfo.reset_tzpath(to=None)

   Sets or resets the time zone search path ("TZPATH") for the module.
   When called with no arguments, "TZPATH" is set to the default
   value.

   Calling "reset_tzpath" will not invalidate the "ZoneInfo" cache,
   and so calls to the primary "ZoneInfo" constructor will only use
   the new "TZPATH" in the case of a cache miss.

   The "to" parameter must be a *sequence* of strings or "os.PathLike"
   and not a string, all of which must be absolute paths. "ValueError"
   will be raised if something other than an absolute path is passed.


Globals
=======

zoneinfo.TZPATH

   A read-only sequence representing the time zone search path -- when
   constructing a "ZoneInfo" from a key, the key is joined to each
   entry in the "TZPATH", and the first file found is used.

   "TZPATH" may contain only absolute paths, never relative paths,
   regardless of how it is configured.

   The object that "zoneinfo.TZPATH" points to may change in response
   to a call to "reset_tzpath()", so it is recommended to use
   "zoneinfo.TZPATH" rather than importing "TZPATH" from "zoneinfo" or
   assigning a long-lived variable to "zoneinfo.TZPATH".

   For more information on configuring the time zone search path, see
   Configurer les sources de données.


Exceptions and warnings
=======================

exception zoneinfo.ZoneInfoNotFoundError

   Raised when construction of a "ZoneInfo" object fails because the
   specified key could not be found on the system. This is a subclass
   of "KeyError".

exception zoneinfo.InvalidTZPathWarning

   Raised when "PYTHONTZPATH" contains an invalid component that will
   be filtered out, such as a relative path.
