zoneinfo
--- IANA time zone support¶
Ajouté 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
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¶
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 :
La valeur par défaut
TZPATH
, lorsqu'elle n'est pas spécifiée autrement, peut être configurée à la compilation.TZPATH
peut être configuré en utilisant une variable d'environnement.À 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 dansPYTHONTZPATH
ne sont pas utilisés, mais le comportement reste défini par l'implémentation lorsqu'un chemin relatif est spécifié. CPython lèveInvalidTZPathWarning
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înekey
. Les appels au constructeur principal renvoient toujours des objets dont la comparaison est identique ; autrement dit, sauf invalidation du cache viaZoneInfo.clear_cache()
, pour toutes les valeurs dekey
, 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èveValueError
si une clé non conforme est passée.Si aucun fichier correspondant à
key
n'est trouvé, le constructeur lèveZoneInfoNotFoundError
.
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 objetio.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
ouAsia/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 :
ZoneInfo(key)
: lorsqu’il est construit avec le constructeur primaire, un objetZoneInfo
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, sieurope_berlin_pkl
est une chaîne contenant un objet sérialisé construit à partir deZoneInfo("Europe/Berlin")
, on s’attend au comportement suivant :>>> a = ZoneInfo("Europe/Berlin") >>> b = pickle.loads(europe_berlin_pkl) >>> a is b True
ZoneInfo.no_cache(key)
: lorsqu’il est construit à partir du constructeur de contournement de cache, l’objetZoneInfo
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. Sieurope_berlin_pkl_nc
est une chaîne contenant un objet sérialisé construit à partir deZoneInfo.no_cache("Europe/Berlin")
, le comportement suivant est attendu :>>> a = ZoneInfo("Europe/Berlin") >>> b = pickle.loads(europe_berlin_pkl_nc) >>> a is b False
ZoneInfo.from_file(fobj, /, key=None)
: lorsqu’il est construit à partir d’un fichier, l’objetZoneInfo
lève une exception lors de la sérialisation. Si un utilisateur souhaite récupérer uneZoneInfo
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/
etright/
, ou la zoneposixrules
.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 cacheZoneInfo
, donc les appels au constructeur primaireZoneInfo
n’utiliseront le nouveauTZPATH
qu’en cas d’échec du cache.Le paramètre
to
doit être une séquence de chaînes ouos.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 leTZPATH
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’utiliserzoneinfo.TZPATH
plutôt que d’importerTZPATH
dezoneinfo
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 deKeyError
.
- exception zoneinfo.InvalidTZPathWarning¶
Levée lorsque
PYTHONTZPATH
contient un composant non valide qui ne sera pas retenu, tel qu’un chemin relatif.