zoneinfo — Unterstützung für IANA-Zeitzonen

Hinzugefügt in Version 3.9.

Quellcode: Lib/zoneinfo

Das Modul zoneinfo bietet eine konkrete Zeitzonenimplementierung zur Unterstützung der IANA-Zeitzonendatenbank, wie sie ursprünglich in PEP 615 spezifiziert wurde. Standardmäßig verwendet zoneinfo die Zeitzonendaten des Systems, falls verfügbar; falls keine System-Zeitzonendaten verfügbar sind, greift die Bibliothek auf das erstklassige Paket tzdata zurück, das auf PyPI verfügbar ist.

Siehe auch

Modul: datetime

Stellt die Typen time und datetime bereit, mit denen die Klasse ZoneInfo verwendet werden soll.

Paket tzdata

Erstklassiges Paket, das von den CPython-Kernentwicklern gepflegt wird, um Zeitzonendaten über PyPI bereitzustellen.

Verfügbarkeit: nicht WASI.

Dieses Modul funktioniert nicht oder ist nicht auf WebAssembly verfügbar. Weitere Informationen finden Sie unter WebAssembly-Plattformen.

Verwendung von ZoneInfo

ZoneInfo ist eine konkrete Implementierung der abstrakten Basisklasse datetime.tzinfo und ist dafür gedacht, an tzinfo angehängt zu werden, entweder über den Konstruktor, die Methode datetime.replace oder 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'

So konstruierte Datumsangaben sind mit der Datumsarithmetik kompatibel und verarbeiten Übergänge der Sommerzeit ohne weitere Eingriffe.

>>> dt_add = dt + timedelta(days=1)

>>> print(dt_add)
2020-11-01 12:00:00-08:00

>>> dt_add.tzname()
'PST'

Diese Zeitzonen unterstützen auch das Attribut fold, das in PEP 495 eingeführt wurde. Während Offset-Übergängen, die Mehrdeutigkeitszeiten verursachen (wie ein Übergang von Sommerzeit zu Normalzeit), wird der Offset vor dem Übergang verwendet, wenn fold=0 ist, und der Offset nach dem Übergang wird verwendet, wenn fold=1 ist, zum Beispiel

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

Beim Konvertieren aus einer anderen Zeitzone wird der Fold auf den korrekten Wert gesetzt.

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

Datenquellen

Das Modul zoneinfo liefert keine Zeitzonendaten direkt, sondern bezieht Zeitzoneninformationen aus der Zeitzonendatenbank des Systems oder dem erstklassigen PyPI-Paket tzdata, falls verfügbar. Einige Systeme, insbesondere Windows-Systeme, haben keine IANA-Datenbank, und daher wird für Projekte, die auf plattformübergreifende Kompatibilität abzielen und Zeitzonendaten benötigen, empfohlen, eine Abhängigkeit von tzdata zu deklarieren. Wenn weder Systemdaten noch tzdata verfügbar sind, lösen alle Aufrufe von ZoneInfo eine ZoneInfoNotFoundError aus.

Konfiguration der Datenquellen

Wenn ZoneInfo(key) aufgerufen wird, durchsucht der Konstruktor zunächst die Verzeichnisse, die in TZPATH angegeben sind, nach einer Datei, die mit key übereinstimmt, und sucht im Falle eines Fehlers im Paket tzdata nach einer Übereinstimmung. Dieses Verhalten kann auf drei Arten konfiguriert werden:

  1. Der Standard- TZPATH kann, wenn nicht anders angegeben, zur Kompilierzeit konfiguriert werden.

  2. TZPATH kann über eine Umgebungsvariable konfiguriert werden.

  3. Zur Laufzeit kann der Suchpfad mit der Funktion reset_tzpath() manipuliert werden.

Kompilierzeit-Konfiguration

Der Standard- TZPATH enthält mehrere gängige Bereitstellungsorte für die Zeitzonendatenbank (außer unter Windows, wo es keine „bekannten“ Orte für Zeitzonendaten gibt). Unter POSIX-Systemen können nachgelagerte Verteiler und diejenigen, die Python aus dem Quellcode kompilieren und wissen, wo ihre System-Zeitzonendaten bereitgestellt werden, den Standard-Zeitzonenpfad ändern, indem sie die Kompilierzeitoption TZPATH (oder wahrscheinlicher das configure Flag --with-tzpath) angeben, was ein durch os.pathsep getrennter String sein sollte.

Auf allen Plattformen ist der konfigurierte Wert als Schlüssel TZPATH in sysconfig.get_config_var() verfügbar.

Umgebungskonfiguration

Bei der Initialisierung von TZPATH (entweder beim Import oder wann immer reset_tzpath() ohne Argumente aufgerufen wird) verwendet das Modul zoneinfo die Umgebungsvariable PYTHONTZPATH, falls sie existiert, um den Suchpfad festzulegen.

PYTHONTZPATH

Dies ist ein durch os.pathsep getrennter String, der den zu verwendenden Zeitzonensuchpfad enthält. Er muss ausschließlich absolute Pfade enthalten. Relative Komponenten, die in PYTHONTZPATH angegeben sind, werden nicht verwendet, aber ansonsten ist das Verhalten bei Angabe eines relativen Pfads implementierungsabhängig; CPython löst eine InvalidTZPathWarning aus, aber andere Implementierungen können die fehlerhafte Komponente stillschweigend ignorieren oder eine Ausnahme auslösen.

Um das System so einzustellen, dass es die Systemdaten ignoriert und stattdessen das tzdata-Paket verwendet, setzen Sie PYTHONTZPATH="".

Laufzeit-Konfiguration

Der TZ-Suchpfad kann auch zur Laufzeit mit der Funktion reset_tzpath() konfiguriert werden. Dies ist im Allgemeinen keine ratsame Operation, obwohl es sinnvoll ist, sie in Testfunktionen zu verwenden, die die Verwendung eines bestimmten Zeitzonenpfads (oder das Deaktivieren des Zugriffs auf Systemzeitzonen) erfordern.

Die Klasse ZoneInfo

class zoneinfo.ZoneInfo(key)

Eine konkrete Unterklasse von datetime.tzinfo, die eine IANA-Zeitzone darstellt, die durch den String key spezifiziert wird. Aufrufe des primären Konstruktors geben immer Objekte zurück, die identisch verglichen werden; anders ausgedrückt, unter Ausschluss der Cache-Invalidierung durch ZoneInfo.clear_cache() gilt für alle Werte von key die folgende Assertion immer:

a = ZoneInfo(key)
b = ZoneInfo(key)
assert a is b

key muss die Form eines relativen, normalisierten POSIX-Pfads ohne übergeordnete Verweise haben. Der Konstruktor löst eine ValueError aus, wenn ein nicht konformer Schlüssel übergeben wird.

Wenn keine Datei gefunden wird, die mit key übereinstimmt, löst der Konstruktor eine ZoneInfoNotFoundError aus.

Die Klasse ZoneInfo hat zwei alternative Konstruktoren:

classmethod ZoneInfo.from_file(file_obj, /, key=None)

Konstruiert ein ZoneInfo-Objekt aus einem dateiähnlichen Objekt, das Bytes zurückgibt (z. B. eine im Binärmodus geöffnete Datei oder ein io.BytesIO-Objekt). Im Gegensatz zum primären Konstruktor konstruiert dies immer ein neues Objekt.

Der Parameter key legt den Namen der Zone für die Zwecke von __str__() und __repr__() fest.

Objekte, die über diesen Konstruktor erstellt werden, können nicht gepickelt werden (siehe Pickling).

classmethod ZoneInfo.no_cache(key)

Ein alternativer Konstruktor, der den Cache des Konstruktors umgeht. Er ist identisch mit dem primären Konstruktor, gibt aber bei jedem Aufruf ein neues Objekt zurück. Dies ist höchstwahrscheinlich für Test- oder Demonstrationszwecke nützlich, kann aber auch zur Erstellung eines Systems mit einer anderen Cache-Invalidierungsstrategie verwendet werden.

Über diesen Konstruktor erstellte Objekte umgehen beim Entpickeln auch den Cache eines deserialisierenden Prozesses.

Vorsicht

Die Verwendung dieses Konstruktors kann die Semantik Ihrer Datumsangaben auf überraschende Weise verändern. Verwenden Sie ihn nur, wenn Sie wissen, dass Sie ihn benötigen.

Die folgenden Klassenmethoden sind ebenfalls verfügbar:

classmethod ZoneInfo.clear_cache(*, only_keys=None)

Eine Methode zum Invalidieren des Caches der Klasse ZoneInfo. Wenn keine Argumente übergeben werden, werden alle Caches invalidiert und der nächste Aufruf des primären Konstruktors für jeden Schlüssel gibt eine neue Instanz zurück.

Wenn ein Iterable von Schlüsselnamen an den Parameter only_keys übergeben wird, werden nur die angegebenen Schlüssel aus dem Cache entfernt. Schlüssel, die an only_keys übergeben und nicht im Cache gefunden werden, werden ignoriert.

Warnung

Das Aufrufen dieser Funktion kann die Semantik von Datumsangaben mit ZoneInfo auf überraschende Weise verändern; dies modifiziert den Modulzustand und kann daher weitreichende Auswirkungen haben. Verwenden Sie sie nur, wenn Sie wissen, dass Sie sie benötigen.

Die Klasse hat ein Attribut:

ZoneInfo.key

Dies ist ein schreibgeschütztes Attribut, das den Wert von key zurückgibt, der an den Konstruktor übergeben wurde, welcher ein Nachschlüssel in der IANA-Zeitzonendatenbank sein sollte (z. B. America/New_York, Europe/Paris oder Asia/Tokyo).

Für Zonen, die aus einer Datei ohne Angabe eines key-Parameters konstruiert wurden, wird dieser auf None gesetzt.

Hinweis

Obwohl es eine gängige Praxis ist, diese für Endbenutzer verfügbar zu machen, sind diese Werte als Primärschlüssel für die Darstellung der relevanten Zonen und nicht unbedingt als benutzerorientierte Elemente gedacht. Projekte wie CLDR (das Unicode Common Locale Data Repository) können verwendet werden, um benutzerfreundlichere Strings aus diesen Schlüsseln zu erhalten.

Zeichenkettendarstellungen

Die Zeichenkettendarstellung, die beim Aufruf von str für ein ZoneInfo-Objekt zurückgegeben wird, verwendet standardmäßig das Attribut ZoneInfo.key (siehe den Hinweis zur Verwendung in der Attributdokumentation).

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

Für Objekte, die aus einer Datei ohne Angabe eines key-Parameters konstruiert wurden, greift str auf den Aufruf von repr() zurück. ZoneInfos repr ist implementierungsabhängig und nicht unbedingt zwischen Versionen stabil, aber es wird garantiert, dass es kein gültiger ZoneInfo-Schlüssel ist.

Pickle-Serialisierung

Anstatt alle Übergangsdaten zu serialisieren, werden ZoneInfo-Objekte nach Schlüssel serialisiert, und ZoneInfo-Objekte, die aus Dateien konstruiert wurden (selbst solche mit einem angegebenen key-Wert), können nicht gepickelt werden.

Das Verhalten einer ZoneInfo-Datei hängt davon ab, wie sie konstruiert wurde.

  1. ZoneInfo(key): Wenn mit dem primären Konstruktor konstruiert, wird ein ZoneInfo-Objekt nach Schlüssel serialisiert, und bei der Deserialisierung verwendet der deserialisierende Prozess den primären Konstruktor, sodass erwartet wird, dass dies dasselbe Objekt wie andere Referenzen auf dieselbe Zeitzone sind. Wenn beispielsweise europe_berlin_pkl ein String ist, der einen Pickle enthält, der aus ZoneInfo("Europe/Berlin") konstruiert wurde, wäre folgendes Verhalten zu erwarten:

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

  2. ZoneInfo.no_cache(key): Wenn aus dem Cache umgehenden Konstruktor konstruiert, wird das ZoneInfo-Objekt ebenfalls nach Schlüssel serialisiert, aber bei der Deserialisierung verwendet der deserialisierende Prozess den Cache umgehenden Konstruktor. Wenn europe_berlin_pkl_nc ein String ist, der einen Pickle enthält, der aus ZoneInfo.no_cache("Europe/Berlin") konstruiert wurde, wäre folgendes Verhalten zu erwarten:

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

  3. ZoneInfo.from_file(file_obj, /, key=None): Wenn aus einer Datei konstruiert, löst das ZoneInfo-Objekt beim Pickling eine Ausnahme aus. Wenn ein Endbenutzer ein aus einer Datei konstruiertes ZoneInfo pickeln möchte, wird empfohlen, einen Wrapper-Typ oder eine benutzerdefinierte Serialisierungsfunktion zu verwenden: Entweder Serialisierung nach Schlüssel oder Speichern des Inhalts des Dateiobjekts und dessen Serialisierung.

Diese Methode der Serialisierung erfordert, dass die Zeitzonendaten für den benötigten Schlüssel sowohl auf der serialisierenden als auch auf der deserialisierenden Seite verfügbar sind, ähnlich wie Referenzen auf Klassen und Funktionen in beiden Umgebungen erwartet werden. Sie bedeutet auch, dass keine Garantien für die Konsistenz der Ergebnisse gegeben werden, wenn ein ZoneInfo entpickelt wird, der in einer Umgebung mit einer anderen Version der Zeitzonendaten gepickelt wurde.

Funktionen

zoneinfo.available_timezones()

Gibt ein Set zurück, das alle gültigen Schlüssel für IANA-Zeitzonen enthält, die irgendwo auf dem Zeitzonenpfad verfügbar sind. Dies wird bei jedem Aufruf der Funktion neu berechnet.

Diese Funktion enthält nur kanonische Zonennamen und keine „speziellen“ Zonen wie die unter den Verzeichnissen posix/ und right/ oder die Zone posixrules.

Vorsicht

Diese Funktion kann eine große Anzahl von Dateien öffnen, da der beste Weg, um festzustellen, ob eine Datei auf dem Zeitzonenpfad eine gültige Zeitzone ist, darin besteht, den „Magic-String“ am Anfang zu lesen.

Hinweis

Diese Werte sind nicht für Endbenutzer gedacht; für benutzerorientierte Elemente sollten Anwendungen etwas wie CLDR (das Unicode Common Locale Data Repository) verwenden, um benutzerfreundlichere Zeichenketten zu erhalten. Siehe auch den Hinweis auf ZoneInfo.key.

zoneinfo.reset_tzpath(to=None)

Setzt oder setzt den Zeitzonensuchpfad (TZPATH) für das Modul zurück. Wenn ohne Argumente aufgerufen, wird TZPATH auf den Standardwert gesetzt.

Das Aufrufen von reset_tzpath invalidiert nicht den Cache von ZoneInfo, und daher verwenden Aufrufe des primären ZoneInfo-Konstruktors den neuen TZPATH nur im Falle eines Cache-Fehlers.

Der Parameter to muss eine Sequenz von Strings oder os.PathLike sein und kein String. Alle diese müssen absolute Pfade sein. Eine ValueError wird ausgelöst, wenn etwas anderes als ein absoluter Pfad übergeben wird.

Globale Variablen

zoneinfo.TZPATH

Eine schreibgeschützte Sequenz, die den Zeitzonensuchpfad darstellt – beim Konstruieren einer ZoneInfo aus einem Schlüssel wird der Schlüssel an jeden Eintrag im TZPATH angehängt, und die erste gefundene Datei wird verwendet.

TZPATH darf unabhängig von der Konfiguration nur absolute Pfade und niemals relative Pfade enthalten.

Das Objekt, auf das zoneinfo.TZPATH verweist, kann sich als Reaktion auf einen Aufruf von reset_tzpath() ändern. Daher wird empfohlen, zoneinfo.TZPATH zu verwenden, anstatt TZPATH aus zoneinfo zu importieren oder eine langlaufende Variable auf zoneinfo.TZPATH zuzuweisen.

Weitere Informationen zur Konfiguration des Zeitzonensuchpfads finden Sie unter Konfiguration der Datenquellen.

Ausnahmen und Warnungen

exception zoneinfo.ZoneInfoNotFoundError

Wird ausgelöst, wenn die Konstruktion eines ZoneInfo-Objekts fehlschlägt, weil der angegebene Schlüssel nicht im System gefunden werden konnte. Dies ist eine Unterklasse von KeyError.

exception zoneinfo.InvalidTZPathWarning

Wird ausgelöst, wenn PYTHONTZPATH eine ungültige Komponente enthält, die herausgefiltert wird, z. B. ein relativer Pfad.