Attribute

Instanzen der Klassen datetime.time und datetime.datetime erhalten ein neues Attribut fold mit zwei möglichen Werten: 0 und 1.

Konstruktoren

Die Methoden __new__ der Klassen datetime.time und datetime.datetime erhalten ein neues schlüsselwortexklusives Argument namens fold mit dem Standardwert 0. Der Wert des Arguments fold wird verwendet, um den Wert des Attributs fold in der zurückgegebenen Instanz zu initialisieren.

Methoden

Die Methoden replace() der Klassen datetime.time und datetime.datetime erhalten ein neues schlüsselwortexklusives Argument namens fold. Es verhält sich ähnlich wie die anderen replace()-Argumente: Wenn das Argument fold angegeben und mit dem Wert 0 oder 1 versehen ist, wird das von replace() zurückgegebene neue Instanz das Attribut fold auf diesen Wert gesetzt haben. In CPython löst jeder nicht-ganzzahlige Wert von fold einen TypeError aus, aber andere Implementierungen können zulassen, dass der Wert None sich genauso verhält, als wäre fold nicht angegeben. [4] (Dies ist eine Anspielung auf den bestehenden Unterschied in der Behandlung von None-Argumenten in anderen Positionen dieser Methode über Python-Implementierungen hinweg; es ist nicht beabsichtigt, die Tür für zukünftige alternative Interpretationen von fold=None offen zu lassen.) Wenn das Argument fold nicht angegeben ist, wird der ursprüngliche Wert des Attributs fold in das Ergebnis kopiert.

C-API

Zugriffs-Makros werden definiert, um den Wert von fold aus PyDateTime_DateTime und PyDateTime_Time-Objekten zu extrahieren.

int PyDateTime_DATE_GET_FOLD(PyDateTime_DateTime *o)

Gibt den Wert von fold als C int zurück.

int PyDateTime_TIME_GET_FOLD(PyDateTime_Time *o)

Gibt den Wert von fold als C int zurück.

Neue Konstruktoren werden definiert, die ein zusätzliches Argument zum Festlegen des Werts von fold in der erstellten Instanz erhalten.

PyObject* PyDateTime_FromDateAndTimeAndFold(
    int year, int month, int day, int hour, int minute,
    int second, int usecond, int fold)

Gibt ein datetime.datetime-Objekt mit dem angegebenen Jahr, Monat, Tag, Stunde, Minute, Sekunde, Mikrosekunde und Fold zurück.

PyObject* PyTime_FromTimeAndFold(
    int hour, int minute, int second, int usecond, int fold)

Gibt ein datetime.time-Objekt mit der angegebenen Stunde, Minute, Sekunde, Mikrosekunde und Fold zurück.

Wie spät ist es?

Die Methode datetime.now(), ohne Argumente aufgerufen, setzt fold=1, wenn sie die zweite der beiden mehrdeutigen Zeiten in einem System-Lokalzeit-Fold zurückgibt. Wenn sie mit einem tzinfo-Argument aufgerufen wird, wird der Wert von fold durch die tzinfo.fromutc()-Implementierung bestimmt. Wenn eine Instanz der Klasse datetime.timezone (die Standardbibliotheks-Unterklasse für feste Offset-Zeitzonen, z. B. datetime.timezone.utc) als tzinfo übergeben wird, hat die zurückgegebene Datetime-Instanz immer fold=0. Die Methode datetime.utcnow() ist davon unberührt.

Konvertierung von naiv zu bewusst

Es wird eine neue Funktion vorgeschlagen, um die Konvertierung von naiven Datetime-Instanzen in bewusste zu erleichtern.

Die Methode astimezone() funktioniert nun auch für naive self. In diesem Fall wird die System-Lokalzeitzone angenommen, und das fold-Flag wird verwendet, um zu bestimmen, welche Lokalzeitzone im mehrdeutigen Fall gültig ist.

Zum Beispiel, auf einem System, das auf die US/Eastern-Zeitzone eingestellt ist

>>> dt = datetime(2014, 11, 2, 1, 30)
>>> dt.astimezone().strftime('%D %T %Z%z')
'11/02/14 01:30:00 EDT-0400'
>>> dt.replace(fold=1).astimezone().strftime('%D %T %Z%z')
'11/02/14 01:30:00 EST-0500'

Eine Folge davon ist, dass datetime.now(tz) vollständig äquivalent zu datetime.now().astimezone(tz) ist (vorausgesetzt, tz ist eine Instanz einer Post-PEP-Implementierung von tzinfo, d.h. eine, die fold korrekt verarbeitet und setzt).

Konvertierung von POSIX-Sekunden seit EPOCH

Die statische Methode fromtimestamp() von datetime.datetime setzt das Attribut fold im zurückgegebenen Objekt entsprechend.

Zum Beispiel, auf einem System, das auf die US/Eastern-Zeitzone eingestellt ist

>>> datetime.fromtimestamp(1414906200)
datetime.datetime(2014, 11, 2, 1, 30)
>>> datetime.fromtimestamp(1414906200 + 3600)
datetime.datetime(2014, 11, 2, 1, 30, fold=1)

Konvertierung zu POSIX-Sekunden seit EPOCH

Die Methode timestamp() von datetime.datetime gibt unterschiedliche Werte für datetime.datetime-Instanzen zurück, die sich nur durch den Wert ihres fold-Attributs unterscheiden, und zwar nur dann, wenn diese Instanzen eine mehrdeutige oder fehlende Zeit darstellen.

Wenn eine datetime.datetime-Instanz dt eine mehrdeutige Zeit darstellt, gibt es zwei Werte s0 und s1, so dass

datetime.fromtimestamp(s0) == datetime.fromtimestamp(s1) == dt

(Dies liegt daran, dass == den Wert von fold ignoriert – siehe unten.)

In diesem Fall gibt dt.timestamp() den kleineren der Werte s0 und s1 zurück, wenn dt.fold == 0 ist, und den größeren sonst.

Zum Beispiel, auf einem System, das auf die US/Eastern-Zeitzone eingestellt ist

>>> datetime(2014, 11, 2, 1, 30, fold=0).timestamp()
1414906200.0
>>> datetime(2014, 11, 2, 1, 30, fold=1).timestamp()
1414909800.0

Wenn eine datetime.datetime-Instanz dt eine fehlende Zeit darstellt, gibt es keinen Wert s, für den

datetime.fromtimestamp(s) == dt

aber wir können zwei „nice to know“-Werte von s bilden, die sich um die Größe der Lücke in Sekunden unterscheiden. Einer ist der Wert von s, der dt in einer Zeitzone entsprechen würde, in der der UTC-Offset immer derselbe ist wie der Offset unmittelbar vor der Lücke, und der andere ist der ähnliche Wert, aber in einer Zeitzone, in der der UTC-Offset immer derselbe ist wie der Offset unmittelbar nach der Lücke.

Der von dt.timestamp() zurückgegebene Wert für ein fehlendes dt ist der größere der beiden „nice to know“-Werte, wenn dt.fold == 0 ist, und der kleinere sonst. (Dies ist kein Tippfehler – es ist absichtlich rückwärts gerichtet gegenüber der Regel für mehrdeutige Zeiten.)

Zum Beispiel, auf einem System, das auf die US/Eastern-Zeitzone eingestellt ist

>>> datetime(2015, 3, 8, 2, 30, fold=0).timestamp()
1425799800.0
>>> datetime(2015, 3, 8, 2, 30, fold=1).timestamp()
1425796200.0

Bewusste Datetime-Instanzen

Benutzer von Pre-PEP-Implementierungen von tzinfo werden keine Änderungen im Verhalten ihrer bewussten Datetime-Instanzen feststellen. Zwei solche Instanzen, die sich nur durch den Wert des fold-Attributs unterscheiden, sind durch nichts anderes als durch direkten Zugriff auf den fold-Wert unterscheidbar. (Dies liegt daran, dass diese Pre-PEP-Implementierungen das fold-Attribut nicht verwenden.)

Wenn andererseits tzinfo eines Objekts auf eine Fold-fähige Implementierung gesetzt ist, dann beeinflusst im Fold oder in der Lücke der Wert von fold das Ergebnis mehrerer Methoden: utcoffset(), dst(), tzname(), astimezone(), strftime() (wenn die Direktive „%Z“ oder „%z“ in der Formatangabe verwendet wird), isoformat() und timetuple().

Kombinieren und Aufteilen von Datum und Zeit

Die Methode datetime.datetime.combine() kopiert den Wert des Attributs fold in die resultierende datetime.datetime-Instanz.

Die Methode datetime.datetime.time() kopiert den Wert des Attributs fold in die resultierende datetime.time-Instanz.

Pickles

Der Wert des Fold-Attributs wird nur in Pickles gespeichert, die mit dem Protokollversion 4 (eingeführt in Python 3.4) oder höher erstellt wurden.

Die Pickle-Größen für die Objekte datetime.datetime und datetime.time ändern sich nicht. Der fold-Wert wird im ersten Bit des 3. Bytes der datetime.datetime-Pickle-Nutzlast kodiert; und im ersten Bit des 1. Bytes der datetime.time-Nutzlast. In der aktuellen Implementierung werden diese Bytes verwendet, um die Monats- (1-12) und Stundenwerte (0-23) zu speichern, und das erste Bit ist immer 0. Wir haben diese Bytes gewählt, da sie die einzigen sind, die vom aktuellen Unpickle-Code überprüft werden. Das Laden von Pre-PEP fold=1-Pickles in einem Pre-PEP-Python führt daher zu einer Ausnahme anstelle einer Instanz mit Komponenten außerhalb des Bereichs.

Eine nicht-technische Antwort

• Alice: Bob – lass uns morgen um 01:30 Uhr eine Sternenbeobachtungsparty machen!
• Bob: Soll ich annehmen, dass die Sommerzeit für die angegebene Zeit in Kraft ist oder nicht?
• Alice: Hä?

• Bob: Alice – lass uns morgen um 01:30 Uhr eine Sternenbeobachtungsparty machen!
• Alice: Weißt du, Bob, 01:30 Uhr wird morgen zweimal vorkommen. An welche Zeit denkst du?
• Bob: Daran habe ich nicht gedacht, aber nehmen wir die erste.

(die gleichen Charaktere, eine Stunde später)

• Bob: Alice – dieses Py-O-Clock-Gadget von mir fragt mich nach der Wahl zwischen fold=0 und fold=1, wenn ich es für morgen 01:30 Uhr einstelle. Was soll ich tun?
• Alice: Ich habe noch nie von einem Py-O-Clock gehört, aber ich schätze, fold=0 ist das erste 01:30 Uhr und fold=1 ist das zweite.

Ein technischer Grund

Während das Feld tm_isdst des time.struct_time-Objekts zur Entambiguierung lokaler Zeiten in Bezug auf den "fold" verwendet werden kann, sind die Semantiken einer solchen Entambiguierung völlig anders als der Vorschlag in diesem PEP.

Das Hauptproblem mit dem Feld tm_isdst ist, dass es unmöglich ist zu wissen, welcher Wert für tm_isdst angemessen ist, ohne die Details über die Zeitzone zu kennen, die nur der tzinfo-Implementierung zur Verfügung stehen. Daher ist tm_isdst zwar nützlich bei der **Ausgabe** von Methoden wie time.localtime, aber umständlich als **Eingabe** für Methoden wie time.mktime.

Wenn der Programmierer einen nicht-negativen Wert von tm_isdst für time.mktime falsch angegeben hat, wird das Ergebnis eine Zeit sein, die 1 Stunde daneben liegt. Da es selten eine Möglichkeit gibt, etwas über die Sommerzeit **vor** einem Aufruf von time.mktime zu wissen, ist die einzig sinnvolle Wahl normalerweise tm_isdst=-1.

Im Gegensatz zu tm_isdst hat das vorgeschlagene fold-Attribut keinen Einfluss auf die Interpretation der Datetime-Instanz, es sei denn, es wären ohne dieses Attribut zwei (oder keine) Interpretationen möglich.

Da es sehr verwirrend wäre, etwas namens isdst zu haben, das nicht dieselben Semantiken wie tm_isdst hat, benötigen wir einen anderen Namen. Außerdem hat die Klasse datetime.datetime bereits eine Methode namens dst(), und wenn wir fold "isdst" nennen würden, gäbe es zwangsläufig Situationen, in denen "isdst" Null wäre, aber dst() nicht, oder umgekehrt.

Abwärtskompatibilität

Es wurde vorgeschlagen, dass die Abwärtskompatibilität verbessert werden könnte, wenn der Standardwert des fold-Flags None wäre, was signalisieren würde, dass das Verhalten vor dem PEP angefordert wird. Basierend auf der unten stehenden Analyse glauben wir, dass die vorgeschlagenen Änderungen mit dem fold=0-Standard ausreichend abwärtskompatibel sind.

Dieses PEP bietet nur drei Möglichkeiten für ein Programm, zu erkennen, dass zwei ansonsten identische Datetime-Instanzen unterschiedliche Werte für fold haben: (1) eine explizite Prüfung des fold-Attributs; (2) wenn die Instanzen naiv sind - Konvertierung in eine andere Zeitzone mittels der astimezone()-Methode; und (3) Konvertierung in float mittels der timestamp()-Methode.

Da fold ein neues Attribut ist, ist die erste Option für bestehende Programme nicht verfügbar. Beachten Sie, dass Option (2) nur für naive Datumsangaben funktioniert, die zufällig in einem "fold" oder einer Lücke in der Systemzeitzone liegen. In allen anderen Fällen wird der Wert von fold bei der Konvertierung ignoriert, es sei denn, die Instanzen verwenden eine fold-bewusste tzinfo, die in einem Programm vor dem PEP nicht verfügbar wäre. Ebenso ist astimezone(), das auf einer naiven Instanz aufgerufen wird, in einem solchen Programm nicht verfügbar, da astimezone() derzeit nicht mit naiven Datumsangaben funktioniert.

Dies lässt uns mit nur einer Situation, in der ein bestehendes Programm nach der Implementierung dieses PEP unterschiedliche Ergebnisse liefern kann: wenn eine datetime.timestamp()-Methode auf einer naiven Datetime-Instanz aufgerufen wird, die zufällig in einem Fold oder einer Lücke liegt. In der aktuellen Implementierung ist das Ergebnis undefiniert. Abhängig von der System- mktime-Implementierung können die Programme in diesen Fällen unterschiedliche Ergebnisse oder Fehler sehen. Mit diesem PEP wird der Zeitstempelwert in diesen Fällen gut definiert sein, aber vom Wert des fold-Flags abhängen. Wir betrachten die Änderung des Verhaltens der datetime.timestamp()-Methode als Fehlerbehebung, die durch dieses PEP ermöglicht wird. Das alte Verhalten kann von Benutzern, die darauf angewiesen sind, weiterhin emuliert werden, indem sie time.mktime(dt.timetuple()) + 1e-6*dt.microsecond anstelle von dt.timestamp() schreiben.

Analogie zu tm_isdst

Die time.mktime-Schnittstelle erlaubt drei Werte für das tm_isdst-Flag: -1, 0 und 1. Wie wir oben erklärt haben, ist -1 (was mktime auffordert, anhand der restlichen Felder zu ermitteln, ob die Sommerzeit für die gegebene Zeit gilt) die einzige praktisch nützliche Wahl.

Mit dem fold-Flag gibt datetime.timestamp() jedoch in 99,98 % der Fälle für die meisten Zeitzonen mit Sommerzeitübergängen denselben Wert zurück wie mktime mit tm_isdst=-1. Darüber hinaus ist das Verhalten ähnlich wie tm_isdst=-1 **unabhängig** vom Wert von fold spezifiziert.

Nur in den 0,02 % der Fälle (2 Stunden pro Jahr) können datetime.timestamp() und mktime mit tm_isdst=-1 abweichen. Doch selbst in diesem Fall werden die meisten mktime-Implementierungen den Wert fold=0 oder den Wert fold=1 zurückgeben, obwohl relevante Standards mktime erlauben, -1 zurückzugeben und in diesen Fällen einen Fehlercode zu setzen.

Mit anderen Worten, das Verhalten von tm_isdst=-1 fehlt in diesem PEP nicht. Im Gegenteil, es ist das einzige Verhalten, das in zwei verschiedenen gut definierten Varianten bereitgestellt wird. Das fehlende Verhalten ist, wenn eine gegebene lokale Stunde aufgrund des falsch spezifizierten tm_isdst als eine andere lokale Stunde interpretiert wird.

Zum Beispiel kann man in den Sommerzeit beobachtenden Zeitzonen der Nordhalbkugel (wo die Sommerzeit im Juni in Kraft ist) Folgendes erhalten:

>>> from time import mktime, localtime
>>> t = mktime((2015, 6, 1, 12, 0, 0, -1, -1, 0))
>>> localtime(t)[:]
(2015, 6, 1, 13, 0, 0, 0, 152, 1)

Beachten Sie, dass 12:00 von mktime als 13:00 interpretiert wurde. Mit datetime.timestamp und datetime.fromtimestamp ist derzeit garantiert, dass

>>> t = datetime.datetime(2015, 6, 1, 12).timestamp()
>>> datetime.datetime.fromtimestamp(t)
datetime.datetime(2015, 6, 1, 12, 0)

Dieses PEP erweitert dieselbe Garantie auf beide Werte von fold.

>>> t = datetime.datetime(2015, 6, 1, 12, fold=0).timestamp()
>>> datetime.datetime.fromtimestamp(t)
datetime.datetime(2015, 6, 1, 12, 0)

>>> t = datetime.datetime(2015, 6, 1, 12, fold=1).timestamp()
>>> datetime.datetime.fromtimestamp(t)
datetime.datetime(2015, 6, 1, 12, 0)

Somit ist einer der vorgeschlagenen Verwendungszwecke für fold=-1 – um das Legacy-Verhalten abzugleichen – nicht erforderlich. Jede Wahl von fold wird das alte Verhalten abgleichen, mit Ausnahme der wenigen Fälle, in denen das alte Verhalten undefiniert war.

Strikte Prüfung ungültiger Zeiten

Ein weiterer Vorschlag war, fold=-1 oder fold=None zu verwenden, um anzuzeigen, dass das Programm wirklich keine Möglichkeit hat, mit den Folds und Lücken umzugehen, und dt.utcoffset() einen Fehler auslösen sollte, wann immer dt eine mehrdeutige oder fehlende lokale Zeit darstellt.

Das Hauptproblem mit diesem Vorschlag ist, dass dt.utcoffset() intern in Situationen verwendet wird, in denen das Auslösen eines Fehlers keine Option ist: zum Beispiel bei Dictionary-Lookups oder Listen-/Set-Mitgliedschaftsprüfungen. Eine strenge Lücken-/Fold-Prüfung müsste daher durch ein separates Flag gesteuert werden, z. B. dt.utcoffset(raise_on_gap=True, raise_on_fold=False). Diese Funktionalität kann jedoch leicht im Benutzercode implementiert werden.

def utcoffset(dt, raise_on_gap=True, raise_on_fold=False):
    u = dt.utcoffset()
    v = dt.replace(fold=not dt.fold).utcoffset()
    if u == v:
        return u
    if (u < v) == dt.fold:
        if raise_on_fold:
            raise AmbiguousTimeError
    else:
        if raise_on_gap:
            raise MissingTimeError
    return u

Darüber hinaus ist das Auslösen eines Fehlers in den Problemfällen nur eine von vielen möglichen Lösungen. Ein interaktives Programm kann den Benutzer um zusätzliche Eingaben bitten, während ein Serverprozess eine Warnung protokollieren und eine angemessene Standardaktion durchführen kann. Wir können unmöglich Funktionen für alle möglichen Benutzeranforderungen bereitstellen, aber dieses PEP bietet die Mittel, um jedes gewünschte Verhalten in wenigen Codezeilen zu implementieren.