zoneinfo — Prise en charge des fuseaux horaires IANA

Nouveau dans la version 3.9.

Code source : 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.

Voir aussi

Module : datetime

Fournit les types time et datetime attendus par ZoneInfo.

Package tzdata

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

Availability: not WASI.

This module does not work or is not available on WebAssembly. See Plateformes WebAssembly for more information.

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

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.

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

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.

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.