zoneinfo
— Prise en charge des fuseaux horaires IANA¶
Nouveau dans la version 3.9.
Source code: 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
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 :
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¶
The default TZPATH
includes several common deployment locations for the
time zone database (except on Windows, where there are no "well-known"
locations for time zone data). On POSIX systems, downstream distributors and
those building Python from source who know where their system
time zone data is deployed may change the default time zone path by specifying
the compile-time option TZPATH
(or, more likely, the configure
flag --with-tzpath
), which should be a string delimited by
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
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
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¶
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:
ZoneInfo(key)
: When constructed with the primary constructor, aZoneInfo
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, ifeurope_berlin_pkl
is a string containing a pickle constructed fromZoneInfo("Europe/Berlin")
, one would expect the following behavior:>>> a = ZoneInfo("Europe/Berlin") >>> b = pickle.loads(europe_berlin_pkl) >>> a is b True
ZoneInfo.no_cache(key)
: When constructed from the cache-bypassing constructor, theZoneInfo
object is also serialized by key, but when deserialized, the deserializing process uses the cache bypassing constructor. Ifeurope_berlin_pkl_nc
is a string containing a pickle constructed fromZoneInfo.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
ZoneInfo.from_file(fobj, /, key=None)
: When constructed from a file, theZoneInfo
object raises an exception on pickling. If an end user wants to pickle aZoneInfo
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/
andright/
directories, or theposixrules
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 theZoneInfo
cache, and so calls to the primaryZoneInfo
constructor will only use the newTZPATH
in the case of a cache miss.The
to
parameter must be a sequence of strings oros.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 theTZPATH
, 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 toreset_tzpath()
, so it is recommended to usezoneinfo.TZPATH
rather than importingTZPATH
fromzoneinfo
or assigning a long-lived variable tozoneinfo.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 ofKeyError
.
-
exception
zoneinfo.
InvalidTZPathWarning
¶ Raised when
PYTHONTZPATH
contains an invalid component that will be filtered out, such as a relative path.