datetime — Grundlegende Datums- und Zeittypen

Quellcode: Lib/datetime.py

Das Modul datetime stellt Klassen zur Bearbeitung von Daten und Zeiten bereit.

Während Datum- und Zeitarithmetik unterstützt wird, liegt der Fokus der Implementierung auf der effizienten Extraktion von Attributen für die Ausgabeformatierung und -bearbeitung.

Tipp

Springen Sie zu den Formatcodes.

Siehe auch

Modul calendar

Allgemeine kalenderbezogene Funktionen.

Modul time

Zeitzugriff und -konvertierungen.

Modul zoneinfo

Konkrete Zeitzonen, die die IANA-Zeitzonendatenbank darstellen.

Paket dateutil

Drittanbieterbibliothek mit erweiterter Unterstützung für Zeitzonen und Parsing.

Paket DateType

Drittanbieterbibliothek, die unterscheidbare statische Typen einführt, um z. B. statische Typ-Checker zwischen naiven und bewussten Datums- und Zeitangaben unterscheiden zu lassen.

Bewusste und naive Objekte

Datums- und Zeitobjekte können als „bewusst“ oder „naiv“ kategorisiert werden, je nachdem, ob sie Zeitzoneninformationen enthalten oder nicht.

Mit ausreichendem Wissen über anwendbare algorithmische und politische Zeitanpassungen, wie Zeitzonen- und Sommerzeitinformationen, kann ein **bewusstes** Objekt sich relativ zu anderen bewussten Objekten lokalisieren. Ein bewusstes Objekt repräsentiert einen bestimmten Zeitpunkt, der keiner Interpretation offensteht. [1]

Ein **naives** Objekt enthält nicht genügend Informationen, um sich eindeutig relativ zu anderen Datums-/Zeitobjekten zu lokalisieren. Ob ein naives Objekt die koordinierte Weltzeit (UTC), die Lokalzeit oder eine Zeit in einer anderen Zeitzone repräsentiert, liegt allein beim Programm, genau wie es beim Programm liegt, ob eine bestimmte Zahl Meter, Meilen oder Masse darstellt. Naive Objekte sind einfach zu verstehen und zu handhaben, auf Kosten der Ignorierung einiger Aspekte der Realität.

Für Anwendungen, die bewusste Objekte benötigen, verfügen datetime- und time-Objekte über ein optionales Zeitzoneninformationsattribut, tzinfo, das auf eine Instanz einer Unterklasse der abstrakten tzinfo-Klasse gesetzt werden kann. Diese tzinfo-Objekte erfassen Informationen über die Abweichung von der UTC-Zeit, den Namen der Zeitzone und ob die Sommerzeit in Kraft ist.

Nur eine konkrete tzinfo-Klasse, die timezone-Klasse, wird vom Modul datetime bereitgestellt. Die timezone-Klasse kann einfache Zeitzonen mit festen Abweichungen von UTC darstellen, wie z. B. UTC selbst oder die nordamerikanischen Zeitzonen EST und EDT. Die Unterstützung von Zeitzonen mit detaillierteren Regeln obliegt der Anwendung. Die Regeln für Zeitanpassungen auf der ganzen Welt sind eher politisch als rational, ändern sich häufig, und es gibt keine für jede Anwendung geeignete Standard außer UTC.

Konstanten

Das Modul datetime exportiert folgende Konstanten

datetime.MINYEAR

Die kleinste erlaubte Jahreszahl in einem date- oder datetime-Objekt. MINYEAR ist 1.

datetime.MAXYEAR

Die größte erlaubte Jahreszahl in einem date- oder datetime-Objekt. MAXYEAR ist 9999.

datetime.UTC

Alias für das UTC-Zeitzonen-Singleton datetime.timezone.utc.

Hinzugefügt in Version 3.11.

Verfügbare Typen

class datetime.date

Ein idealisiertes naives Datum, das davon ausgeht, dass der aktuelle Gregorianische Kalender immer gültig war und immer gültig sein wird. Attribute: year, month und day.

class datetime.time

Eine idealisierte Zeit, unabhängig von einem bestimmten Tag, unter der Annahme, dass jeder Tag genau 24*60*60 Sekunden hat. (Hier gibt es keine „Schaltsekunden“.) Attribute: hour, minute, second, microsecond und tzinfo.

class datetime.datetime

Eine Kombination aus Datum und Uhrzeit. Attribute: year, month, day, hour, minute, second, microsecond und tzinfo.

class datetime.timedelta

Eine Dauer, die die Differenz zwischen zwei datetime- oder date-Instanzen mit Mikrosekundenauflösung ausdrückt.

class datetime.tzinfo

Eine abstrakte Basisklasse für Zeitzoneninformationsobjekte. Diese werden von den Klassen datetime und time verwendet, um eine anpassbare Vorstellung von Zeitanpassungen (z. B. zur Berücksichtigung von Zeitzonen und/oder Sommerzeit) bereitzustellen.

class datetime.timezone

Eine Klasse, die die abstrakte Basisklasse tzinfo als feste Abweichung von UTC implementiert.

Hinzugefügt in Version 3.2.

Objekte dieser Typen sind unveränderlich.

Unterklassenbeziehungen

object
    timedelta
    tzinfo
        timezone
    time
    date
        datetime

Gemeinsame Eigenschaften

Die Typen date, datetime, time und timezone teilen sich diese gemeinsamen Merkmale

  • Objekte dieser Typen sind unveränderlich.

  • Objekte dieser Typen sind hashable, was bedeutet, dass sie als Schlüssel in Wörterbüchern verwendet werden können.

  • Objekte dieser Typen unterstützen effizientes Pickling über das Modul pickle.

Feststellen, ob ein Objekt bewusst oder naiv ist

Objekte des Typs date sind immer naiv.

Ein Objekt vom Typ time oder datetime kann bewusst oder naiv sein.

Ein datetime-Objekt d ist bewusst, wenn beides zutrifft

  1. d.tzinfo ist nicht None

  2. d.tzinfo.utcoffset(d) gibt nicht None zurück

Andernfalls ist d naiv.

Ein time-Objekt t ist bewusst, wenn beides zutrifft

  1. t.tzinfo ist nicht None

  2. t.tzinfo.utcoffset(None) gibt nicht None zurück.

Andernfalls ist t naiv.

Die Unterscheidung zwischen bewusst und naiv trifft auf timedelta-Objekte nicht zu.

timedelta-Objekte

Ein timedelta-Objekt repräsentiert eine Dauer, die Differenz zwischen zwei datetime- oder date-Instanzen.

class datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)

Alle Argumente sind optional und standardmäßig 0. Argumente können ganze Zahlen oder Gleitkommazahlen sein und positiv oder negativ sein.

Nur *Tage*, *Sekunden* und *Mikrosekunden* werden intern gespeichert. Argumente werden in diese Einheiten umgewandelt

  • Eine Millisekunde wird in 1000 Mikrosekunden umgewandelt.

  • Eine Minute wird in 60 Sekunden umgewandelt.

  • Eine Stunde wird in 3600 Sekunden umgewandelt.

  • Eine Woche wird in 7 Tage umgewandelt.

und Tage, Sekunden und Mikrosekunden werden dann normalisiert, sodass die Darstellung eindeutig ist, mit

  • 0 <= Mikrosekunden < 1000000

  • 0 <= Sekunden < 3600*24 (die Anzahl der Sekunden in einem Tag)

  • -999999999 <= Tage <= 999999999

Das folgende Beispiel verdeutlicht, wie alle Argumente außer *Tage*, *Sekunden* und *Mikrosekunden* „zusammengefasst“ und in diese drei resultierenden Attribute normalisiert werden

>>> from datetime import timedelta
>>> delta = timedelta(
...     days=50,
...     seconds=27,
...     microseconds=10,
...     milliseconds=29000,
...     minutes=5,
...     hours=8,
...     weeks=2
... )
>>> # Only days, seconds, and microseconds remain
>>> delta
datetime.timedelta(days=64, seconds=29156, microseconds=10)

Wenn ein Argument eine Gleitkommazahl ist und es Bruchteile von Mikrosekunden gibt, werden die verbleibenden Bruchteile von allen Argumenten kombiniert und ihre Summe wird zur nächsten Mikrosekunde gerundet, wobei die round-half-to-even-Regel für Gleichstände angewendet wird. Wenn kein Argument eine Gleitkommazahl ist, sind die Konvertierungs- und Normalisierungsprozesse exakt (es gehen keine Informationen verloren).

Wenn der normalisierte Wert von Tagen außerhalb des angegebenen Bereichs liegt, wird OverflowError ausgelöst.

Beachten Sie, dass die Normalisierung negativer Werte auf den ersten Blick überraschend sein kann. Zum Beispiel

>>> from datetime import timedelta
>>> d = timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)

Da die String-Darstellung von timedelta-Objekten verwirrend sein kann, verwenden Sie das folgende Rezept, um ein lesbareres Format zu erzeugen

>>> def pretty_timedelta(td):
...     if td.days >= 0:
...         return str(td)
...     return f'-({-td!s})'
...
>>> d = timedelta(hours=-1)
>>> str(d)  # not human-friendly
'-1 day, 23:00:00'
>>> pretty_timedelta(d)
'-(1:00:00)'

Klassenattribute

timedelta.min

Das negativste timedelta-Objekt, timedelta(-999999999).

timedelta.max

Das positivste timedelta-Objekt, timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999).

timedelta.resolution

Die kleinstmögliche Differenz zwischen ungleichen timedelta-Objekten, timedelta(microseconds=1).

Beachten Sie, dass aufgrund der Normalisierung timedelta.max größer ist als -timedelta.min. -timedelta.max ist nicht als timedelta-Objekt darstellbar.

Instanzattribute (schreibgeschützt)

timedelta.days

Zwischen -999.999.999 und 999.999.999 einschließlich.

timedelta.seconds

Zwischen 0 und 86.399 einschließlich.

Vorsicht

Es ist ein häufiger Fehler, dass Code dieses Attribut unbeabsichtigt verwendet, wenn eigentlich ein total_seconds()-Wert gemeint ist

>>> from datetime import timedelta
>>> duration = timedelta(seconds=11235813)
>>> duration.days, duration.seconds
(130, 3813)
>>> duration.total_seconds()
11235813.0
timedelta.microseconds

Zwischen 0 und 999.999 einschließlich.

Unterstützte Operationen

Operation

Ergebnis

t1 = t2 + t3

Summe von t2 und t3. Danach gilt t1 - t2 == t3 und t1 - t3 == t2. (1)

t1 = t2 - t3

Differenz von t2 und t3. Danach gilt t1 == t2 - t3 und t2 == t1 + t3. (1)(6)

t1 = t2 * i oder t1 = i * t2

Delta multipliziert mit einer ganzen Zahl. Danach gilt t1 // i == t2, vorausgesetzt i != 0.

Allgemein gilt t1  * i == t1 * (i-1) + t1. (1)

t1 = t2 * f oder t1 = f * t2

Delta multipliziert mit einer Gleitkommazahl. Das Ergebnis wird auf das nächste Vielfache von timedelta.resolution gerundet, wobei round-half-to-even verwendet wird.

f = t2 / t3

Division (3) der Gesamt dauer t2 durch die Intervall einheit t3. Gibt ein float-Objekt zurück.

t1 = t2 / f oder t1 = t2 / i

Delta geteilt durch eine Gleitkommazahl oder eine ganze Zahl. Das Ergebnis wird auf das nächste Vielfache von timedelta.resolution gerundet, wobei round-half-to-even verwendet wird.

t1 = t2 // i oder t1 = t2 // t3

Der ganzzahlige Anteil wird berechnet und der Rest (falls vorhanden) wird verworfen. Im zweiten Fall wird eine ganze Zahl zurückgegeben. (3)

t1 = t2 % t3

Der Rest wird als timedelta-Objekt berechnet. (3)

q, r = divmod(t1, t2)

Berechnet den Quotienten und den Rest: q = t1 // t2 (3) und r = t1 % t2. q ist eine ganze Zahl und r ist ein timedelta-Objekt.

+t1

Gibt ein timedelta-Objekt mit demselben Wert zurück. (2)

-t1

Entspricht timedelta(-t1.days, -t1.seconds, -t1.microseconds) und t1 * -1. (1)(4)

abs(t)

Entspricht +t wenn t.days >= 0 und -t wenn t.days < 0. (2)

str(t)

Gibt eine Zeichenkette im Format [T Tage[n], ][H]H:MM:SS[.UUUUUU] zurück, wobei T negativ für negative t ist. (5)

repr(t)

Gibt eine String-Darstellung des timedelta-Objekts als Konstruktoraufruf mit kanonischen Attributwerten zurück.

Hinweise

  1. Dies ist exakt, kann aber überlaufen.

  2. Dies ist exakt und kann nicht überlaufen.

  3. Division durch Null löst ZeroDivisionError aus.

  4. -timedelta.max ist nicht als timedelta-Objekt darstellbar.

  5. String-Darstellungen von timedelta-Objekten werden ähnlich wie ihre interne Darstellung normalisiert. Dies führt zu etwas ungewöhnlichen Ergebnissen für negative Zeitspannen. Zum Beispiel

    >>> timedelta(hours=-5)
datetime.timedelta(days=-1, seconds=68400)
>>> print(_)
-1 day, 19:00:00

  6. Der Ausdruck t2 - t3 ist immer gleich dem Ausdruck t2 + (-t3), außer wenn t3 gleich timedelta.max ist; in diesem Fall liefert der erste ein Ergebnis, während der zweite überläuft.

Zusätzlich zu den oben aufgeführten Operationen unterstützen timedelta-Objekte bestimmte Additionen und Subtraktionen mit date- und datetime-Objekten (siehe unten).

Geändert in Version 3.2: Ganzzahlige Division und reelle Division eines timedelta-Objekts durch ein anderes timedelta-Objekt werden nun unterstützt, ebenso wie Restoperationen und die divmod()-Funktion. Reelle Division und Multiplikation eines timedelta-Objekts durch ein float-Objekt werden nun unterstützt.

timedelta-Objekte unterstützen Gleichheits- und Ordnungsvergleiche.

In booleschen Kontexten wird ein timedelta-Objekt genau dann als wahr betrachtet, wenn es nicht gleich timedelta(0) ist.

Instanzmethoden

timedelta.total_seconds()

Gibt die Gesamtzahl der Sekunden in der Dauer zurück. Entspricht td / timedelta(seconds=1). Für andere Einheiten als Sekunden verwenden Sie direkt die Divisionsform (z.B. td / timedelta(microseconds=1)).

Beachten Sie, dass diese Methode bei sehr großen Zeitintervallen (auf den meisten Plattformen mehr als 270 Jahre) die Mikrosekunden-Genauigkeit verliert.

Hinzugefügt in Version 3.2.

Anwendungsbeispiele: timedelta

Ein zusätzliches Beispiel für Normalisierung

>>> # Components of another_year add up to exactly 365 days
>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> another_year = timedelta(weeks=40, days=84, hours=23,
...                          minutes=50, seconds=600)
>>> year == another_year
True
>>> year.total_seconds()
31536000.0

Beispiele für timedelta-Arithmetik

>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> ten_years = 10 * year
>>> ten_years
datetime.timedelta(days=3650)
>>> ten_years.days // 365
10
>>> nine_years = ten_years - year
>>> nine_years
datetime.timedelta(days=3285)
>>> three_years = nine_years // 3
>>> three_years, three_years.days // 365
(datetime.timedelta(days=1095), 3)

date Objekte

Ein date-Objekt repräsentiert ein Datum (Jahr, Monat und Tag) in einem idealisierten Kalender, dem aktuellen gregorianischen Kalender, der in beide Richtungen unbegrenzt erweitert ist.

Der 1. Januar des Jahres 1 wird als Tag Nummer 1 bezeichnet, der 2. Januar des Jahres 1 als Tag Nummer 2 und so weiter. [2]

class datetime.date(year, month, day)

Alle Argumente sind erforderlich. Die Argumente müssen Ganzzahlen sein und innerhalb der folgenden Bereiche liegen

  • MINYEAR <= year <= MAXYEAR

  • 1 <= month <= 12

  • 1 <= day <= Anzahl der Tage im gegebenen Monat und Jahr

Wenn ein Argument außerhalb dieser Bereiche angegeben wird, wird ValueError ausgelöst.

Andere Konstruktoren, alle Klassenmethoden

classmethod date.today()

Gibt das aktuelle lokale Datum zurück.

Dies entspricht date.fromtimestamp(time.time()).

classmethod date.fromtimestamp(timestamp)

Gibt das lokale Datum zurück, das dem POSIX-Timestamp entspricht, wie er von time.time() zurückgegeben wird.

Dies kann OverflowError auslösen, wenn der Timestamp außerhalb des Bereichs der von der plattformspezifischen C-Funktion localtime() unterstützten Werte liegt, und OSError bei einem Fehler von localtime(). Es ist üblich, dass dies auf Jahre von 1970 bis 2038 beschränkt ist. Beachten Sie, dass auf Nicht-POSIX-Systemen, die Schaltsekunden in ihrer Zeitmessung berücksichtigen, Schaltsekunden von fromtimestamp() ignoriert werden.

Geändert in Version 3.3: Löst OverflowError anstelle von ValueError aus, wenn der Timestamp außerhalb des Bereichs der von der plattformspezifischen C-Funktion localtime() unterstützten Werte liegt. Löst OSError anstelle von ValueError bei einem Fehler von localtime() aus.

classmethod date.fromordinal(ordinal)

Gibt das Datum zurück, das dem proleptischen gregorianischen Ordinalzahl entspricht, bei dem der 1. Januar des Jahres 1 die Ordinalzahl 1 hat.

ValueError wird ausgelöst, es sei denn, 1 <= ordinal <= date.max.toordinal(). Für jedes Datum d gilt: date.fromordinal(d.toordinal()) == d.

classmethod date.fromisoformat(date_string)

Gibt ein date zurück, das einer date_string in einem beliebigen gültigen ISO 8601-Format entspricht, mit den folgenden Ausnahmen

  1. Daten mit reduzierter Genauigkeit werden derzeit nicht unterstützt (YYYY-MM, YYYY).

  2. Erweiterte Datumsdarstellungen werden derzeit nicht unterstützt (±YYYYYY-MM-DD).

  3. Ordinaldatumsangaben werden derzeit nicht unterstützt (YYYY-OOO).

Beispiele

>>> from datetime import date
>>> date.fromisoformat('2019-12-04')
datetime.date(2019, 12, 4)
>>> date.fromisoformat('20191204')
datetime.date(2019, 12, 4)
>>> date.fromisoformat('2021-W01-1')
datetime.date(2021, 1, 4)

Hinzugefügt in Version 3.7.

Geändert in Version 3.11: Zuvor unterstützte diese Methode nur das Format YYYY-MM-DD.

classmethod date.fromisocalendar(year, week, day)

Gibt ein date zurück, das dem durch Jahr, Woche und Tag angegebenen ISO-Kalenderdatum entspricht. Dies ist die Umkehrung der Funktion date.isocalendar().

Hinzugefügt in Version 3.8.

classmethod date.strptime(date_string, format)

Gibt ein date zurück, das der date_string entspricht, analysiert gemäß format. Dies entspricht

date(*(time.strptime(date_string, format)[0:3]))

ValueError wird ausgelöst, wenn die date_string und das Format nicht von time.strptime() analysiert werden können oder wenn ein Wert zurückgegeben wird, der kein Zeittupel ist. Siehe auch strftime() und strptime() Verhalten und date.fromisoformat().

Hinweis

Wenn format einen Tag ohne Jahr angibt, wird eine DeprecationWarning ausgegeben. Dies dient dazu, einen vierjährigen Schaltjahresfehler in Code zu vermeiden, der nur einen Monat und Tag als Standardjahr analysieren möchte, wenn keines im Format angegeben ist, da dieses Standardjahr kein Schaltjahr ist. Solche format-Werte können ab Python 3.15 eine Fehlermeldung auslösen. Die Umgehung besteht darin, immer ein Jahr in Ihrem format einzuschließen. Wenn Sie date_string-Werte parsen, die kein Jahr enthalten, fügen Sie explizit ein Schaltjahr hinzu, bevor Sie parsen.

>>> from datetime import date
>>> date_string = "02/29"
>>> when = date.strptime(f"{date_string};1984", "%m/%d;%Y")  # Avoids leap year bug.
>>> when.strftime("%B %d")
'February 29'

Hinzugefügt in Version 3.14.

Klassenattribute

date.min

Das früheste darstellbare Datum, date(MINYEAR, 1, 1).

date.max

Das späteste darstellbare Datum, date(MAXYEAR, 12, 31).

date.resolution

Die kleinste mögliche Differenz zwischen nicht-gleichen Datumsobjekten, timedelta(days=1).

Instanzattribute (schreibgeschützt)

date.year

Zwischen MINYEAR und MAXYEAR einschließlich.

date.month

Zwischen 1 und 12 einschließlich.

date.day

Zwischen 1 und der Anzahl der Tage im gegebenen Monat des gegebenen Jahres.

Unterstützte Operationen

Operation

Ergebnis

date2 = date1 + timedelta

date2 ist timedelta.days Tage nach date1. (1)

date2 = date1 - timedelta

Berechnet date2 so, dass date2 + timedelta == date1. (2)

timedelta = date1 - date2

(3)
date1 == date2
date1 != date2

Gleichheitsvergleich. (4)
date1 < date2
date1 > date2
date1 <= date2
date1 >= date2

Ordnungsvergleich. (5)

Hinweise

  1. date2 wird in die Zukunft verschoben, wenn timedelta.days > 0, oder in die Vergangenheit, wenn timedelta.days < 0. Danach gilt date2 - date1 == timedelta.days. timedelta.seconds und timedelta.microseconds werden ignoriert. OverflowError wird ausgelöst, wenn date2.year kleiner als MINYEAR oder größer als MAXYEAR wäre.

  2. timedelta.seconds und timedelta.microseconds werden ignoriert.

  3. Dies ist exakt und kann nicht überlaufen. timedelta.seconds und timedelta.microseconds sind 0, und danach gilt date2 + timedelta == date1.

  4. date-Objekte sind gleich, wenn sie dasselbe Datum darstellen.

    date-Objekte, die keine datetime-Instanzen sind, sind niemals gleich datetime-Objekten, selbst wenn sie dasselbe Datum darstellen.

  5. date1 wird als kleiner als date2 betrachtet, wenn date1 zeitlich vor date2 liegt. Anders ausgedrückt, date1 < date2 genau dann, wenn date1.toordinal() < date2.toordinal().

    Der Ordnungsvergleich zwischen einem date-Objekt, das keine datetime-Instanz ist, und einem datetime-Objekt löst TypeError aus.

Geändert in Version 3.13: Der Vergleich zwischen einem datetime-Objekt und einer Instanz der date-Unterklasse, die keine datetime-Unterklasse ist, konvertiert letztere nicht mehr zu date, wobei der Zeitteil und die Zeitzone ignoriert werden. Das Standardverhalten kann durch Überschreiben der speziellen Vergleichsmethoden in Unterklassen geändert werden.

In booleschen Kontexten werden alle date-Objekte als wahr betrachtet.

Instanzmethoden

date.replace(year=self.year, month=self.month, day=self.day)

Gibt ein neues date-Objekt mit denselben Werten zurück, jedoch mit aktualisierten angegebenen Parametern.

Beispiel

>>> from datetime import date
>>> d = date(2002, 12, 31)
>>> d.replace(day=26)
datetime.date(2002, 12, 26)

Die generische Funktion copy.replace() unterstützt auch date-Objekte.

date.timetuple()

Gibt ein time.struct_time zurück, wie es von time.localtime() zurückgegeben wird.

Stunden, Minuten und Sekunden sind 0, und das DST-Flag ist -1.

d.timetuple() entspricht

time.struct_time((d.year, d.month, d.day, 0, 0, 0, d.weekday(), yday, -1))

wobei yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1 die Tagesnummer innerhalb des aktuellen Jahres ist, beginnend mit 1 für den 1. Januar.

date.toordinal()

Gibt die proleptische gregorianische Ordinalzahl des Datums zurück, wobei der 1. Januar des Jahres 1 die Ordinalzahl 1 hat. Für jedes date-Objekt d gilt: date.fromordinal(d.toordinal()) == d.

date.weekday()

Gibt den Wochentag als ganze Zahl zurück, wobei Montag 0 und Sonntag 6 ist. Zum Beispiel: date(2002, 12, 4).weekday() == 2, ein Mittwoch. Siehe auch isoweekday().

date.isoweekday()

Gibt den Wochentag als ganze Zahl zurück, wobei Montag 1 und Sonntag 7 ist. Zum Beispiel: date(2002, 12, 4).isoweekday() == 3, ein Mittwoch. Siehe auch weekday(), isocalendar().

date.isocalendar()

Gibt ein named tuple-Objekt mit drei Komponenten zurück: year, week und weekday.

Der ISO-Kalender ist eine weit verbreitete Variante des gregorianischen Kalenders. [3]

Das ISO-Jahr besteht aus 52 oder 53 vollen Wochen, wobei eine Woche am Montag beginnt und am Sonntag endet. Die erste Woche eines ISO-Jahres ist die erste (gregorianische) Kalenderwoche eines Jahres, die einen Donnerstag enthält. Dies wird als Woche Nummer 1 bezeichnet, und das ISO-Jahr dieses Donnerstags ist dasselbe wie sein gregorianisches Jahr.

Zum Beispiel beginnt das Jahr 2004 an einem Donnerstag, daher beginnt die erste Woche des ISO-Jahres 2004 am Montag, dem 29. Dezember 2003 und endet am Sonntag, dem 4. Januar 2004.

>>> from datetime import date
>>> date(2003, 12, 29).isocalendar()
datetime.IsoCalendarDate(year=2004, week=1, weekday=1)
>>> date(2004, 1, 4).isocalendar()
datetime.IsoCalendarDate(year=2004, week=1, weekday=7)

Geändert in Version 3.9: Das Ergebnis wurde von einem Tupel in ein named tuple geändert.

date.isoformat()

Gibt eine Zeichenkette zurück, die das Datum im ISO 8601-Format darstellt: YYYY-MM-DD

>>> from datetime import date
>>> date(2002, 12, 4).isoformat()
'2002-12-04'
date.__str__()

Für ein Datum d ist str(d) äquivalent zu d.isoformat().

date.ctime()

Gibt eine Zeichenkette zurück, die das Datum darstellt

>>> from datetime import date
>>> date(2002, 12, 4).ctime()
'Wed Dec  4 00:00:00 2002'

d.ctime() entspricht

time.ctime(time.mktime(d.timetuple()))

auf Plattformen, auf denen die native C-Funktion ctime() (die von time.ctime() aufgerufen wird, aber nicht von date.ctime()) dem C-Standard entspricht.

date.strftime(format)

Gibt eine Zeichenkette zurück, die das Datum darstellt und durch eine explizite Formatzeichenkette gesteuert wird. Formatcodes, die sich auf Stunden, Minuten oder Sekunden beziehen, zeigen 0-Werte an. Siehe auch strftime() und strptime() Verhalten und date.isoformat().

date.__format__(format)

Identisch mit date.strftime(). Dies ermöglicht die Angabe einer Formatzeichenkette für ein date-Objekt in formatierten Zeichenketten-Literalen und bei Verwendung von str.format(). Siehe auch strftime() und strptime() Verhalten und date.isoformat().

Anwendungsbeispiele: date

Beispiel für die Berechnung von Tagen bis zu einem Ereignis

>>> import time
>>> from datetime import date
>>> today = date.today()
>>> today
datetime.date(2007, 12, 5)
>>> today == date.fromtimestamp(time.time())
True
>>> my_birthday = date(today.year, 6, 24)
>>> if my_birthday < today:
...     my_birthday = my_birthday.replace(year=today.year + 1)
...
>>> my_birthday
datetime.date(2008, 6, 24)
>>> time_to_birthday = abs(my_birthday - today)
>>> time_to_birthday.days
202

Weitere Beispiele für die Arbeit mit date

>>> from datetime import date
>>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001
>>> d
datetime.date(2002, 3, 11)

>>> # Methods related to formatting string output
>>> d.isoformat()
'2002-03-11'
>>> d.strftime("%d/%m/%y")
'11/03/02'
>>> d.strftime("%A %d. %B %Y")
'Monday 11. March 2002'
>>> d.ctime()
'Mon Mar 11 00:00:00 2002'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, "day", "month")
'The day is 11, the month is March.'

>>> # Methods for to extracting 'components' under different calendars
>>> t = d.timetuple()
>>> for i in t:
...     print(i)
2002                # year
3                   # month
11                  # day
0
0
0
0                   # weekday (0 = Monday)
70                  # 70th day in the year
-1
>>> ic = d.isocalendar()
>>> for i in ic:
...     print(i)
2002                # ISO year
11                  # ISO week number
1                   # ISO day number ( 1 = Monday )

>>> # A date object is immutable; all operations produce a new object
>>> d.replace(year=2005)
datetime.date(2005, 3, 11)

datetime Objekte

Ein datetime-Objekt ist ein einzelnes Objekt, das alle Informationen aus einem date-Objekt und einem time-Objekt enthält.

Wie ein date-Objekt nimmt datetime den aktuellen gregorianischen Kalender an, der in beide Richtungen erweitert ist; wie ein time-Objekt geht datetime davon aus, dass jeder Tag genau 3600*24 Sekunden hat.

Konstruktor

class datetime.datetime(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

Die Argumente year, month und day sind erforderlich. tzinfo kann None oder eine Instanz einer Unterklasse von tzinfo sein. Die restlichen Argumente müssen ganze Zahlen in den folgenden Bereichen sein

  • MINYEAR <= year <= MAXYEAR,

  • 1 <= month <= 12,

  • 1 <= day <= Anzahl der Tage im gegebenen Monat und Jahr,

  • 0 <= hour < 24,

  • 0 <= minute < 60,

  • 0 <= second < 60,

  • 0 <= microsecond < 1000000,

  • fold in [0, 1].

Wenn ein Argument außerhalb dieser Bereiche angegeben wird, wird ValueError ausgelöst.

Geändert in Version 3.6: Parameter fold hinzugefügt.

Andere Konstruktoren, alle Klassenmethoden

classmethod datetime.today()

Gibt das aktuelle lokale Datum und die aktuelle lokale Zeit zurück, mit tzinfo None.

Entspricht

datetime.fromtimestamp(time.time())

Siehe auch now(), fromtimestamp().

Diese Methode ist funktional äquivalent zu now(), aber ohne einen tz Parameter.

classmethod datetime.now(tz=None)

Gibt das aktuelle lokale Datum und die aktuelle lokale Zeit zurück.

Wenn das optionale Argument tz None ist oder nicht angegeben wird, ist dies wie today(), aber wenn möglich, wird eine höhere Präzision als durch ein time.time() Zeitstempel (zum Beispiel kann dies auf Plattformen möglich sein, die die C gettimeofday() Funktion bereitstellen) geliefert.

Wenn tz nicht None ist, muss es eine Instanz einer Unterklasse von tzinfo sein, und das aktuelle Datum und die aktuelle Zeit werden in die Zeitzone von tz konvertiert.

Diese Funktion wird gegenüber today() und utcnow() bevorzugt.

Hinweis

Nachfolgende Aufrufe von datetime.now() können denselben Zeitpunkt zurückgeben, abhängig von der Präzision der zugrunde liegenden Uhr.

classmethod datetime.utcnow()

Gibt das aktuelle UTC-Datum und die aktuelle UTC-Zeit zurück, mit tzinfo None.

Dies ist wie now(), gibt aber das aktuelle UTC-Datum und die aktuelle UTC-Zeit als naives datetime Objekt zurück. Ein informatives aktuelles UTC-Datum und eine aktuelle UTC-Zeit können durch Aufrufen von datetime.now(timezone.utc) erhalten werden. Siehe auch now().

Warnung

Da naive datetime Objekte von vielen datetime Methoden als lokale Zeiten behandelt werden, ist es vorzuziehen, informative Datetime-Objekte zur Darstellung von Zeiten in UTC zu verwenden. Daher ist der empfohlene Weg, ein Objekt zu erstellen, das die aktuelle Zeit in UTC darstellt, durch Aufrufen von datetime.now(timezone.utc).

Veraltet seit Version 3.12: Verwenden Sie stattdessen datetime.now() mit UTC.

classmethod datetime.fromtimestamp(timestamp, tz=None)

Gibt das lokale Datum und die lokale Zeit zurück, die dem POSIX-Zeitstempel entsprechen, wie er von time.time() zurückgegeben wird. Wenn das optionale Argument tz None ist oder nicht angegeben wird, wird der Zeitstempel in das lokale Datum und die lokale Zeit der Plattform konvertiert, und das zurückgegebene datetime Objekt ist naiv.

Wenn tz nicht None ist, muss es eine Instanz einer Unterklasse von tzinfo sein, und der Zeitstempel wird in die Zeitzone von tz konvertiert.

fromtimestamp() kann OverflowError auslösen, wenn der Zeitstempel außerhalb des Bereichs der von den plattformabhängigen C localtime() oder gmtime() Funktionen unterstützten Werte liegt, und OSError bei einem Fehler von localtime() oder gmtime(). Häufig ist dies auf Jahre zwischen 1970 und 2038 beschränkt. Beachten Sie, dass auf Nicht-POSIX-Systemen, die Schaltsekunden in ihrer Zeitstempeldefinition enthalten, Schaltsekunden von fromtimestamp() ignoriert werden und es dann möglich ist, zwei Zeitstempel zu haben, die sich um eine Sekunde unterscheiden und identische datetime Objekte ergeben. Diese Methode wird gegenüber utcfromtimestamp() bevorzugt.

Geändert in Version 3.3: Löst OverflowError anstelle von ValueError aus, wenn der Zeitstempel außerhalb des Bereichs der von den plattformabhängigen C localtime() oder gmtime() Funktionen unterstützten Werte liegt. Löst OSError anstelle von ValueError bei Fehler von localtime() oder gmtime() aus.

Geändert in Version 3.6: fromtimestamp() kann Instanzen mit gesetztem fold auf 1 zurückgeben.

classmethod datetime.utcfromtimestamp(timestamp)

Gibt das UTC- datetime zurück, das dem POSIX-Zeitstempel entspricht, mit tzinfo None. (Das resultierende Objekt ist naiv.)

Dies kann OverflowError auslösen, wenn der Zeitstempel außerhalb des Bereichs der von der plattformabhängigen C gmtime() Funktion unterstützten Werte liegt, und OSError bei einem Fehler von gmtime(). Häufig ist dies auf Jahre zwischen 1970 und 2038 beschränkt.

Um ein informatives datetime Objekt zu erhalten, rufen Sie fromtimestamp() auf.

datetime.fromtimestamp(timestamp, timezone.utc)

Auf POSIX-kompatiblen Plattformen ist dies äquivalent zum folgenden Ausdruck

datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp)

mit Ausnahme, dass die letztere Formel immer den vollen Jahresbereich unterstützt: zwischen MINYEAR und MAXYEAR einschließlich.

Warnung

Da naive datetime Objekte von vielen datetime Methoden als lokale Zeiten behandelt werden, ist es vorzuziehen, informative Datetime-Objekte zur Darstellung von Zeiten in UTC zu verwenden. Daher ist der empfohlene Weg, ein Objekt zu erstellen, das einen bestimmten Zeitstempel in UTC darstellt, durch Aufrufen von datetime.fromtimestamp(timestamp, tz=timezone.utc).

Geändert in Version 3.3: Löst OverflowError anstelle von ValueError aus, wenn der Zeitstempel außerhalb des Bereichs der von der plattformabhängigen C gmtime() Funktion unterstützten Werte liegt. Löst OSError anstelle von ValueError bei Fehler von gmtime() aus.

Veraltet seit Version 3.12: Verwenden Sie stattdessen datetime.fromtimestamp() mit UTC.

classmethod datetime.fromordinal(ordinal)

Gibt das datetime zurück, das dem proleptischen gregorianischen Ordinal entspricht, wobei der 1. Januar des Jahres 1 die Ordinalzahl 1 hat. ValueError wird ausgelöst, es sei denn, 1 <= ordinal <= datetime.max.toordinal(). Stunde, Minute, Sekunde und Mikrosekunde des Ergebnisses sind alle 0, und tzinfo ist None.

classmethod datetime.combine(date, time, tzinfo=time.tzinfo)

Gibt ein neues datetime Objekt zurück, dessen Datumskomponenten mit denen des angegebenen date Objekts übereinstimmen und dessen Zeitkomponenten mit denen des angegebenen time Objekts übereinstimmen. Wenn das Argument tzinfo angegeben ist, wird sein Wert zum Setzen des tzinfo Attributs des Ergebnisses verwendet, andernfalls wird das tzinfo Attribut des time Arguments verwendet. Wenn das date Argument ein datetime Objekt ist, werden seine Zeitkomponenten und tzinfo Attribute ignoriert.

Für jedes datetime Objekt d gilt d == datetime.combine(d.date(), d.time(), d.tzinfo).

Geändert in Version 3.6: Argument tzinfo hinzugefügt.

classmethod datetime.fromisoformat(date_string)

Gibt ein datetime zurück, das einer date_string in einem beliebigen gültigen ISO 8601-Format entspricht, mit folgenden Ausnahmen

  1. Zeitzonen-Offsets können Bruchteilsekunden enthalten.

  2. Der Trenner T kann durch ein beliebiges einzelnes Unicode-Zeichen ersetzt werden.

  3. Gebrochene Stunden und Minuten werden nicht unterstützt.

  4. Daten mit reduzierter Genauigkeit werden derzeit nicht unterstützt (YYYY-MM, YYYY).

  5. Erweiterte Datumsdarstellungen werden derzeit nicht unterstützt (±YYYYYY-MM-DD).

  6. Ordinaldatumsangaben werden derzeit nicht unterstützt (YYYY-OOO).

Beispiele

>>> from datetime import datetime
>>> datetime.fromisoformat('2011-11-04')
datetime.datetime(2011, 11, 4, 0, 0)
>>> datetime.fromisoformat('20111104')
datetime.datetime(2011, 11, 4, 0, 0)
>>> datetime.fromisoformat('2011-11-04T00:05:23')
datetime.datetime(2011, 11, 4, 0, 5, 23)
>>> datetime.fromisoformat('2011-11-04T00:05:23Z')
datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone.utc)
>>> datetime.fromisoformat('20111104T000523')
datetime.datetime(2011, 11, 4, 0, 5, 23)
>>> datetime.fromisoformat('2011-W01-2T00:05:23.283')
datetime.datetime(2011, 1, 4, 0, 5, 23, 283000)
>>> datetime.fromisoformat('2011-11-04 00:05:23.283')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000)
>>> datetime.fromisoformat('2011-11-04 00:05:23.283+00:00')
datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone.utc)
>>> datetime.fromisoformat('2011-11-04T00:05:23+04:00')
datetime.datetime(2011, 11, 4, 0, 5, 23,
    tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))

Hinzugefügt in Version 3.7.

Geändert in Version 3.11: Zuvor unterstützte diese Methode nur Formate, die von date.isoformat() oder datetime.isoformat() ausgegeben werden konnten.

classmethod datetime.fromisocalendar(year, week, day)

Gibt ein datetime zurück, das dem ISO-Kalenderdatum entspricht, das durch Jahr, Woche und Tag spezifiziert ist. Die Nicht-Datum-Komponenten des Datetime werden mit ihren normalen Standardwerten aufgefüllt. Dies ist die Umkehrung der Funktion datetime.isocalendar().

Hinzugefügt in Version 3.8.

classmethod datetime.strptime(date_string, format)

Gibt ein datetime zurück, das der date_string entspricht, geparst gemäß format.

Wenn format keine Mikrosekunden oder Zeitzoneninformationen enthält, ist dies äquivalent zu

datetime(*(time.strptime(date_string, format)[0:6]))

ValueError wird ausgelöst, wenn die date_string und das Format nicht von time.strptime() geparst werden können oder wenn ein Wert zurückgegeben wird, der kein Zeit-Tupel ist. Siehe auch strftime() und strptime() Verhalten und datetime.fromisoformat().

Geändert in Version 3.13: Wenn format einen Tag des Monats ohne Jahr angibt, wird nun eine DeprecationWarning ausgegeben. Dies dient zur Vermeidung eines vierjährigen Schaltjahresfehlers in Code, der nur einen Monat und Tag parsen möchte, da das Standardjahr bei Fehlen eines solchen im Format kein Schaltjahr ist. Solche format-Werte können ab Python 3.15 einen Fehler auslösen. Die Abhilfe besteht darin, immer ein Jahr in Ihrem format anzugeben. Wenn date_string-Werte ohne Jahr geparst werden, fügen Sie explizit ein Schaltjahr hinzu, bevor Sie parsen.

>>> from datetime import datetime
>>> date_string = "02/29"
>>> when = datetime.strptime(f"{date_string};1984", "%m/%d;%Y")  # Avoids leap year bug.
>>> when.strftime("%B %d")
'February 29'

Klassenattribute

datetime.min

Das am frühesten darstellbare datetime, datetime(MINYEAR, 1, 1, tzinfo=None).

datetime.max

Das am spätesten darstellbare datetime, datetime(MAXYEAR, 12, 31, 23, 59, 59, 999999, tzinfo=None).

datetime.resolution

Der kleinstmögliche Unterschied zwischen nicht-gleichen datetime Objekten, timedelta(microseconds=1).

Instanzattribute (schreibgeschützt)

datetime.year

Zwischen MINYEAR und MAXYEAR einschließlich.

datetime.month

Zwischen 1 und 12 einschließlich.

datetime.day

Zwischen 1 und der Anzahl der Tage im gegebenen Monat des gegebenen Jahres.

datetime.hour

In range(24).

datetime.minute

In range(60).

datetime.second

In range(60).

datetime.microsecond

In range(1000000).

datetime.tzinfo

Das als Argument tzinfo an den datetime Konstruktor übergebene Objekt oder None, wenn keines übergeben wurde.

datetime.fold

In [0, 1]. Wird verwendet, um Wandzeiten während eines wiederholten Intervalls zu disambiguieren. (Ein wiederholtes Intervall tritt auf, wenn Uhren am Ende der Sommerzeit zurückgestellt werden oder wenn der UTC-Offset für die aktuelle Zone aus politischen Gründen verringert wird.) Die Werte 0 und 1 repräsentieren jeweils den früheren und den späteren der beiden Momente mit der gleichen Wandzeitdarstellung.

Hinzugefügt in Version 3.6.

Unterstützte Operationen

Operation

Ergebnis

datetime2 = datetime1 + timedelta

(1)

datetime2 = datetime1 - timedelta

(2)

timedelta = datetime1 - datetime2

(3)
datetime1 == datetime2
datetime1 != datetime2

Gleichheitsvergleich. (4)
datetime1 < datetime2
datetime1 > datetime2
datetime1 <= datetime2
datetime1 >= datetime2

Ordnungsvergleich. (5)

  1. datetime2 ist eine Dauer von timedelta, die von datetime1 abgezogen wird. Die Zeit bewegt sich vorwärts, wenn timedelta.days > 0, oder rückwärts, wenn timedelta.days < 0. Das Ergebnis hat das gleiche tzinfo Attribut wie das Eingabe-Datetime, und datetime2 - datetime1 == timedelta danach. OverflowError wird ausgelöst, wenn datetime2.year kleiner als MINYEAR oder größer als MAXYEAR wäre. Beachten Sie, dass keine Zeitzonenanpassungen vorgenommen werden, auch wenn die Eingabe ein informatives Objekt ist.

  2. Berechnet das datetime2, so dass datetime2 + timedelta == datetime1. Wie bei der Addition hat das Ergebnis das gleiche tzinfo Attribut wie das Eingabe-Datetime, und es werden keine Zeitzonenanpassungen vorgenommen, auch wenn die Eingabe informativ ist.

  3. Die Subtraktion eines datetime von einem datetime ist nur definiert, wenn beide Operanden naiv sind oder wenn beide informativ sind. Wenn einer informativ und der andere naiv ist, wird TypeError ausgelöst.

    Wenn beide naiv sind oder beide informativ und dasselbe tzinfo Attribut haben, werden die tzinfo Attribute ignoriert, und das Ergebnis ist ein timedelta Objekt t, so dass datetime2 + t == datetime1. In diesem Fall werden keine Zeitzonenanpassungen vorgenommen.

    Wenn beide informativ sind und unterschiedliche tzinfo Attribute haben, verhält sich a-b so, als ob a und b zuerst in naive UTC-Datetimes konvertiert worden wären. Das Ergebnis ist (a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset()), außer dass die Implementierung niemals überläuft.

  4. datetime Objekte sind gleich, wenn sie dasselbe Datum und dieselbe Uhrzeit darstellen, unter Berücksichtigung der Zeitzone.

    Naive und informative datetime Objekte sind niemals gleich.

    Wenn beide Vergleichswerte informativ sind und dasselbe tzinfo Attribut haben, werden die tzinfo und fold Attribute ignoriert und die Basis-Datetimes werden verglichen. Wenn beide Vergleichswerte informativ sind und unterschiedliche tzinfo Attribute haben, verhält sich der Vergleich so, als ob die Vergleichswerte zuerst in UTC-Datetimes konvertiert worden wären, außer dass die Implementierung niemals überläuft. datetime Instanzen in einem wiederholten Intervall sind niemals gleich datetime Instanzen in einer anderen Zeitzone.

  5. datetime1 gilt als kleiner als datetime2, wenn datetime1 zeitlich vor datetime2 liegt, unter Berücksichtigung der Zeitzone.

    Ordnungsvergleiche zwischen naiven und informativen datetime Objekten lösen TypeError aus.

    Wenn beide Vergleichswerte Zeitzoneninformationen haben und denselben tzinfo-Attributwert besitzen, werden das tzinfo- und das fold-Attribut ignoriert und die Basis-Zeitpunkte werden verglichen. Wenn beide Vergleichswerte Zeitzoneninformationen haben und unterschiedliche tzinfo-Attribute besitzen, verhält sich der Vergleich so, als ob die Vergleichswerte zuerst in UTC-Zeitpunkte konvertiert würden, mit der Ausnahme, dass die Implementierung niemals überläuft.

Geändert in Version 3.3: Gleichheitsvergleiche zwischen Zeitpunkten mit und ohne Zeitzoneninformationen (aware und naive datetime-Instanzen) lösen keinen TypeError mehr aus.

Geändert in Version 3.13: Der Vergleich zwischen einem datetime-Objekt und einer Instanz der date-Unterklasse, die keine datetime-Unterklasse ist, konvertiert letztere nicht mehr zu date, wobei der Zeitteil und die Zeitzone ignoriert werden. Das Standardverhalten kann durch Überschreiben der speziellen Vergleichsmethoden in Unterklassen geändert werden.

Instanzmethoden

datetime.date()

Gibt ein date-Objekt mit demselben Jahr, Monat und Tag zurück.

datetime.time()

Gibt ein time-Objekt mit derselben Stunde, Minute, Sekunde, Mikrosekunde und demselben Fold-Wert zurück. tzinfo ist None. Siehe auch Methode timetz().

Geändert in Version 3.6: Der Fold-Wert wird in das zurückgegebene time-Objekt kopiert.

datetime.timetz()

Gibt ein time-Objekt mit derselben Stunde, Minute, Sekunde, Mikrosekunde, demselben Fold-Wert und demselben `tzinfo`-Attribut zurück. Siehe auch Methode time().

Geändert in Version 3.6: Der Fold-Wert wird in das zurückgegebene time-Objekt kopiert.

datetime.replace(year=self.year, month=self.month, day=self.day, hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)

Gibt ein neues datetime-Objekt mit denselben Attributen zurück, aber mit den angegebenen Parametern aktualisiert. Beachten Sie, dass tzinfo=None angegeben werden kann, um einen naiven Zeitpunkt aus einem bewussten Zeitpunkt ohne Konvertierung von Datum und Zeitdaten zu erstellen.

datetime-Objekte werden auch von der generischen Funktion copy.replace() unterstützt.

Geändert in Version 3.6: Parameter fold hinzugefügt.

datetime.astimezone(tz=None)

Gibt ein datetime-Objekt mit einem neuen tzinfo-Attribut tz zurück und passt die Datums- und Zeitdaten so an, dass das Ergebnis dieselbe UTC-Zeit wie self ist, aber in der Lokalzeit von tz.

Wenn angegeben, muss tz eine Instanz einer Unterklasse von tzinfo sein, und seine Methoden utcoffset() und dst() dürfen nicht None zurückgeben. Wenn self naiv ist, wird angenommen, dass es die System-Lokalzeit darstellt.

Wenn ohne Argumente aufgerufen (oder mit tz=None), wird die System-Lokalzeit als Zielzeitzone angenommen. Das `.tzinfo`-Attribut der konvertierten Zeitpunkt-Instanz wird auf eine Instanz von timezone mit dem von der OS erhaltenen Zeitzonennamen und Offset gesetzt.

Wenn self.tzinfo gleich tz ist, ist self.astimezone(tz) gleich self: Es wird keine Anpassung der Datums- oder Zeitdaten vorgenommen. Andernfalls ist das Ergebnis die Lokalzeit in der Zeitzone tz, die dieselbe UTC-Zeit wie self darstellt: Nach astz = dt.astimezone(tz) sind astz - astz.utcoffset() und dt - dt.utcoffset() gleich in Bezug auf Datum und Zeitdaten.

Wenn Sie lediglich ein timezone-Objekt tz an einen Zeitpunkt dt anhängen möchten, ohne die Datums- und Zeitdaten anzupassen, verwenden Sie dt.replace(tzinfo=tz). Wenn Sie lediglich das timezone-Objekt aus einem bewussten Zeitpunkt dt entfernen möchten, ohne die Datums- und Zeitdaten zu konvertieren, verwenden Sie dt.replace(tzinfo=None).

Beachten Sie, dass die Standardmethode tzinfo.fromutc() in einer Unterklasse von tzinfo überschrieben werden kann, um das von astimezone() zurückgegebene Ergebnis zu beeinflussen. Fehlerfälle ignoriert, verhält sich astimezone() wie

def astimezone(self, tz):
    if self.tzinfo is tz:
        return self
    # Convert self to UTC, and attach the new timezone object.
    utc = (self - self.utcoffset()).replace(tzinfo=tz)
    # Convert from UTC to tz's local time.
    return tz.fromutc(utc)

Geändert in Version 3.3: tz kann nun weggelassen werden.

Geändert in Version 3.6: Die Methode astimezone() kann nun auch auf naive Instanzen angewendet werden, die die System-Lokalzeit repräsentieren.

datetime.utcoffset()

Wenn tzinfo None ist, gibt diese Methode None zurück, andernfalls gibt sie self.tzinfo.utcoffset(self) zurück und löst eine Ausnahme aus, wenn letztere nicht None oder ein timedelta-Objekt mit einer Magnitude kleiner als ein Tag zurückgibt.

Geändert in Version 3.7: Der UTC-Offset ist nicht mehr auf eine ganze Anzahl von Minuten beschränkt.

datetime.dst()

Wenn tzinfo None ist, gibt diese Methode None zurück, andernfalls gibt sie self.tzinfo.dst(self) zurück und löst eine Ausnahme aus, wenn letztere nicht None oder ein timedelta-Objekt mit einer Magnitude kleiner als ein Tag zurückgibt.

Geändert in Version 3.7: Der DST-Offset ist nicht mehr auf eine ganze Anzahl von Minuten beschränkt.

datetime.tzname()

Wenn tzinfo None ist, gibt diese Methode None zurück, andernfalls gibt sie self.tzinfo.tzname(self) zurück und löst eine Ausnahme aus, wenn letztere nicht None oder ein String-Objekt zurückgibt.

datetime.timetuple()

Gibt ein time.struct_time zurück, wie es von time.localtime() zurückgegeben wird.

d.timetuple() entspricht

time.struct_time((d.year, d.month, d.day,
                  d.hour, d.minute, d.second,
                  d.weekday(), yday, dst))

wobei yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1 der Tag des Jahres innerhalb des aktuellen Jahres ist, beginnend mit 1 für den 1. Januar. Das Flag tm_isdst des Ergebnisses wird gemäß der Methode dst() gesetzt: Wenn tzinfo None ist oder dst() None zurückgibt, wird tm_isdst auf -1 gesetzt; andernfalls, wenn dst() einen von Null verschiedenen Wert zurückgibt, wird tm_isdst auf 1 gesetzt; andernfalls wird tm_isdst auf 0 gesetzt.

datetime.utctimetuple()

Wenn die datetime-Instanz d naiv ist, entspricht dies d.timetuple(), mit der Ausnahme, dass tm_isdst unabhängig davon, was d.dst() zurückgibt, auf 0 gesetzt wird. Sommerzeit ist niemals für eine UTC-Zeit aktiv.

Wenn d bewusst ist, wird d in UTC-Zeit normalisiert, indem d.utcoffset() subtrahiert wird, und ein time.struct_time für die normalisierte Zeit zurückgegeben. tm_isdst wird auf 0 gesetzt. Beachten Sie, dass ein OverflowError ausgelöst werden kann, wenn d.year MINYEAR oder MAXYEAR war und die UTC-Anpassung über eine Jahresgrenze hinausgeht.

Warnung

Da naive datetime-Objekte von vielen datetime-Methoden als lokale Zeiten behandelt werden, ist es vorzuziehen, bewusste Zeitpunkte zur Darstellung von Zeiten in UTC zu verwenden; folglich kann die Verwendung von datetime.utctimetuple() irreführende Ergebnisse liefern. Wenn Sie ein naives datetime haben, das UTC repräsentiert, verwenden Sie datetime.replace(tzinfo=timezone.utc), um es bewusst zu machen, wonach Sie datetime.timetuple() verwenden können.

datetime.toordinal()

Gibt die proleptische gregorianische Ordinalzahl des Datums zurück. Dies ist dasselbe wie self.date().toordinal().

datetime.timestamp()

Gibt den POSIX-Zeitstempel zurück, der der datetime-Instanz entspricht. Der Rückgabewert ist ein float, ähnlich dem von time.time() zurückgegebenen Wert.

Naive datetime-Instanzen werden als lokale Zeit angenommen und diese Methode stützt sich auf die plattformspezifische C-Funktion mktime() für die Konvertierung. Da datetime auf vielen Plattformen einen größeren Wertebereich unterstützt als mktime(), kann diese Methode für Zeiten weit in der Vergangenheit oder Zukunft OverflowError oder OSError auslösen.

Für bewusste datetime-Instanzen wird der Rückgabewert wie folgt berechnet:

(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()

Hinzugefügt in Version 3.3.

Geändert in Version 3.6: Die Methode timestamp() verwendet das Attribut fold, um Zeiten während eines wiederholten Intervalls zu disambiguieren.

Hinweis

Es gibt keine Methode, um den POSIX-Zeitstempel direkt aus einer naiven datetime-Instanz zu erhalten, die UTC-Zeit repräsentiert. Wenn Ihre Anwendung diese Konvention verwendet und Ihre Systemzeitzone nicht auf UTC eingestellt ist, können Sie den POSIX-Zeitstempel erhalten, indem Sie tzinfo=timezone.utc angeben

timestamp = dt.replace(tzinfo=timezone.utc).timestamp()

oder indem Sie den Zeitstempel direkt berechnen

timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1)
datetime.weekday()

Gibt den Wochentag als ganze Zahl zurück, wobei Montag 0 und Sonntag 6 ist. Dies ist dasselbe wie self.date().weekday(). Siehe auch isoweekday().

datetime.isoweekday()

Gibt den Wochentag als ganze Zahl zurück, wobei Montag 1 und Sonntag 7 ist. Dies ist dasselbe wie self.date().isoweekday(). Siehe auch weekday(), isocalendar().

datetime.isocalendar()

Gibt ein benanntes Tupel mit drei Komponenten zurück: year, week und weekday. Dies ist dasselbe wie self.date().isocalendar().

datetime.isoformat(sep='T', timespec='auto')

Gibt einen String zurück, der das Datum und die Uhrzeit im ISO 8601-Format repräsentiert

Wenn utcoffset() nicht None zurückgibt, wird ein String angehängt, der den UTC-Offset angibt

  • YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]], wenn microsecond nicht 0 ist

  • YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]], wenn microsecond 0 ist

Beispiele

>>> from datetime import datetime, timezone
>>> datetime(2019, 5, 18, 15, 17, 8, 132263).isoformat()
'2019-05-18T15:17:08.132263'
>>> datetime(2019, 5, 18, 15, 17, tzinfo=timezone.utc).isoformat()
'2019-05-18T15:17:00+00:00'

Das optionale Argument sep (Standard 'T') ist ein Ein-Zeichen-Separator, der zwischen dem Datums- und dem Uhrzeitanteil des Ergebnisses platziert wird. Zum Beispiel

>>> from datetime import tzinfo, timedelta, datetime
>>> class TZ(tzinfo):
...     """A time zone with an arbitrary, constant -06:39 offset."""
...     def utcoffset(self, dt):
...         return timedelta(hours=-6, minutes=-39)
...
>>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'
>>> datetime(2009, 11, 27, microsecond=100, tzinfo=TZ()).isoformat()
'2009-11-27T00:00:00.000100-06:39'

Das optionale Argument timespec gibt die Anzahl der zusätzlichen Zeitkomponenten an, die enthalten werden sollen (Standard ist 'auto'). Es kann einer der folgenden Werte sein:

  • 'auto': Dasselbe wie 'seconds', wenn microsecond 0 ist, und dasselbe wie 'microseconds', andernfalls.

  • 'hours': Schließt die hour im zweistelligen HH-Format ein.

  • 'minutes': Schließt hour und minute im HH:MM-Format ein.

  • 'seconds': Schließt hour, minute und second im HH:MM:SS-Format ein.

  • 'milliseconds': Schließt die vollständige Uhrzeit ein, schneidet aber den Bruchteil der Sekunde auf Millisekunden ab. HH:MM:SS.sss-Format.

  • 'microseconds': Schließt die vollständige Uhrzeit im HH:MM:SS.ffffff-Format ein.

Hinweis

Ausgeschlossene Zeitkomponenten werden abgeschnitten, nicht gerundet.

ValueError wird bei einem ungültigen timespec-Argument ausgelöst.

>>> from datetime import datetime
>>> datetime.now().isoformat(timespec='minutes')
'2002-12-25T00:00'
>>> dt = datetime(2015, 1, 1, 12, 30, 59, 0)
>>> dt.isoformat(timespec='microseconds')
'2015-01-01T12:30:59.000000'

Geändert in Version 3.6: Der Parameter timespec wurde hinzugefügt.

datetime.__str__()

Für eine datetime-Instanz d ist str(d) äquivalent zu d.isoformat(' ').

datetime.ctime()

Gibt einen String zurück, der Datum und Uhrzeit repräsentiert

>>> from datetime import datetime
>>> datetime(2002, 12, 4, 20, 30, 40).ctime()
'Wed Dec  4 20:30:40 2002'

Der Ausgabe-String enthält *keine* Zeitzoneninformationen, unabhängig davon, ob die Eingabe bewusst oder naiv ist.

d.ctime() entspricht

time.ctime(time.mktime(d.timetuple()))

auf Plattformen, auf denen die native C-Funktion ctime() (die time.ctime() aufruft, datetime.ctime() jedoch nicht) dem C-Standard entspricht.

datetime.strftime(format)

Gibt einen String zurück, der Datum und Uhrzeit gemäß einer expliziten Formatzeichenkette repräsentiert. Siehe auch Verhalten von strftime() und strptime() und datetime.isoformat().

datetime.__format__(format)

Dasselbe wie datetime.strftime(). Dies ermöglicht die Angabe einer Formatzeichenkette für ein datetime-Objekt in formatierten Zeichenketten-Literalen und bei Verwendung von str.format(). Siehe auch Verhalten von strftime() und strptime() und datetime.isoformat().

Anwendungsbeispiele: datetime

Beispiele für die Arbeit mit datetime-Objekten

>>> from datetime import datetime, date, time, timezone

>>> # Using datetime.combine()
>>> d = date(2005, 7, 14)
>>> t = time(12, 30)
>>> datetime.combine(d, t)
datetime.datetime(2005, 7, 14, 12, 30)

>>> # Using datetime.now()
>>> datetime.now()
datetime.datetime(2007, 12, 6, 16, 29, 43, 79043)   # GMT +1
>>> datetime.now(timezone.utc)
datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone.utc)

>>> # Using datetime.strptime()
>>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
>>> dt
datetime.datetime(2006, 11, 21, 16, 30)

>>> # Using datetime.timetuple() to get tuple of all attributes
>>> tt = dt.timetuple()
>>> for it in tt:
...     print(it)
...
2006    # year
11      # month
21      # day
16      # hour
30      # minute
0       # second
1       # weekday (0 = Monday)
325     # number of days since 1st January
-1      # dst - method tzinfo.dst() returned None

>>> # Date in ISO format
>>> ic = dt.isocalendar()
>>> for it in ic:
...     print(it)
...
2006    # ISO year
47      # ISO week
2       # ISO weekday

>>> # Formatting a datetime
>>> dt.strftime("%A, %d. %B %Y %I:%M%p")
'Tuesday, 21. November 2006 04:30PM'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}, the {3} is {0:%I:%M%p}.'.format(dt, "day", "month", "time")
'The day is 21, the month is November, the time is 04:30PM.'

Das folgende Beispiel definiert eine Unterklasse von tzinfo, die die Zeitzoneninformationen für Kabul, Afghanistan, erfasst, das bis 1945 +4 UTC und danach +4:30 UTC verwendete.

from datetime import timedelta, datetime, tzinfo, timezone

class KabulTz(tzinfo):
    # Kabul used +4 until 1945, when they moved to +4:30
    UTC_MOVE_DATE = datetime(1944, 12, 31, 20, tzinfo=timezone.utc)

    def utcoffset(self, dt):
        if dt.year < 1945:
            return timedelta(hours=4)
        elif (1945, 1, 1, 0, 0) <= dt.timetuple()[:5] < (1945, 1, 1, 0, 30):
            # An ambiguous ("imaginary") half-hour range representing
            # a 'fold' in time due to the shift from +4 to +4:30.
            # If dt falls in the imaginary range, use fold to decide how
            # to resolve. See PEP495.
            return timedelta(hours=4, minutes=(30 if dt.fold else 0))
        else:
            return timedelta(hours=4, minutes=30)

    def fromutc(self, dt):
        # Follow same validations as in datetime.tzinfo
        if not isinstance(dt, datetime):
            raise TypeError("fromutc() requires a datetime argument")
        if dt.tzinfo is not self:
            raise ValueError("dt.tzinfo is not self")

        # A custom implementation is required for fromutc as
        # the input to this function is a datetime with utc values
        # but with a tzinfo set to self.
        # See datetime.astimezone or fromtimestamp.
        if dt.replace(tzinfo=timezone.utc) >= self.UTC_MOVE_DATE:
            return dt + timedelta(hours=4, minutes=30)
        else:
            return dt + timedelta(hours=4)

    def dst(self, dt):
        # Kabul does not observe daylight saving time.
        return timedelta(0)

    def tzname(self, dt):
        if dt >= self.UTC_MOVE_DATE:
            return "+04:30"
        return "+04"

Verwendung von KabulTz aus dem obigen Beispiel

>>> tz1 = KabulTz()

>>> # Datetime before the change
>>> dt1 = datetime(1900, 11, 21, 16, 30, tzinfo=tz1)
>>> print(dt1.utcoffset())
4:00:00

>>> # Datetime after the change
>>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=tz1)
>>> print(dt2.utcoffset())
4:30:00

>>> # Convert datetime to another time zone
>>> dt3 = dt2.astimezone(timezone.utc)
>>> dt3
datetime.datetime(2006, 6, 14, 8, 30, tzinfo=datetime.timezone.utc)
>>> dt2
datetime.datetime(2006, 6, 14, 13, 0, tzinfo=KabulTz())
>>> dt2 == dt3
True

time-Objekte

Ein time-Objekt repräsentiert eine (lokale) Tageszeit, unabhängig von einem bestimmten Datum und vorbehaltlich der Anpassung durch ein tzinfo-Objekt.

class datetime.time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

Alle Argumente sind optional. tzinfo kann None oder eine Instanz einer tzinfo-Unterklasse sein. Die restlichen Argumente müssen ganze Zahlen in den folgenden Bereichen sein:

  • 0 <= hour < 24,

  • 0 <= minute < 60,

  • 0 <= second < 60,

  • 0 <= microsecond < 1000000,

  • fold in [0, 1].

Wenn ein Argument außerhalb dieser Bereiche angegeben wird, wird ValueError ausgelöst. Alle Standardwerte sind 0, außer tzinfo, das auf None gesetzt ist.

Klassenattribute

time.min

Die früheste darstellbare time, time(0, 0, 0, 0).

time.max

Die späteste darstellbare time, time(23, 59, 59, 999999).

time.resolution

Die kleinste mögliche Differenz zwischen ungleichen time-Objekten, timedelta(microseconds=1), obwohl zu beachten ist, dass die Arithmetik mit time-Objekten nicht unterstützt wird.

Instanzattribute (schreibgeschützt)

time.hour

In range(24).

time.minute

In range(60).

time.second

In range(60).

time.microsecond

In range(1000000).

time.tzinfo

Das als tzinfo-Argument an den time-Konstruktor übergebene Objekt oder None, wenn keines übergeben wurde.

time.fold

In [0, 1]. Wird verwendet, um Wandzeiten während eines wiederholten Intervalls zu disambiguieren. (Ein wiederholtes Intervall tritt auf, wenn Uhren am Ende der Sommerzeit zurückgestellt werden oder wenn der UTC-Offset für die aktuelle Zone aus politischen Gründen verringert wird.) Die Werte 0 und 1 repräsentieren jeweils den früheren und den späteren der beiden Momente mit der gleichen Wandzeitdarstellung.

Hinzugefügt in Version 3.6.

time-Objekte unterstützen Gleichheits- und Ordnungsvergleiche, wobei a als kleiner als b betrachtet wird, wenn a zeitlich vor b liegt.

Naive und "aware" (zeitzoneninformierte) time-Objekte sind niemals gleich. Ordnungsvergleiche zwischen naiven und "aware" time-Objekten lösen TypeError aus.

Wenn beide Vergleichsoperanden "aware" sind und das gleiche tzinfo-Attribut haben, werden die tzinfo- und fold-Attribute ignoriert und die Basiszeiten verglichen. Wenn beide Vergleichsoperanden "aware" sind und unterschiedliche tzinfo-Attribute haben, werden die Vergleichsoperanden zuerst durch Subtraktion ihrer UTC-Offsets (erhalten von self.utcoffset()) angepasst.

Geändert in Version 3.3: Gleichheitsvergleiche zwischen "aware" und naiven time-Instanzen lösen keinen TypeError aus.

In booleschen Kontexten wird ein time-Objekt immer als wahr betrachtet.

Geändert in Version 3.5: Vor Python 3.5 wurde ein time-Objekt als falsch betrachtet, wenn es Mitternacht in UTC repräsentierte. Dieses Verhalten wurde als obskur und fehleranfällig angesehen und in Python 3.5 entfernt. Weitere Details finden Sie unter bpo-13936.

Andere Konstruktoren

classmethod time.fromisoformat(time_string)

Gibt eine time zurück, die einer time_string in jedem gültigen ISO 8601-Format entspricht, mit den folgenden Ausnahmen:

  1. Zeitzonen-Offsets können Bruchteilsekunden enthalten.

  2. Das führende T, das normalerweise in Fällen erforderlich ist, in denen es eine Mehrdeutigkeit zwischen Datum und Uhrzeit geben kann, ist nicht erforderlich.

  3. Bruchteile von Sekunden können eine beliebige Anzahl von Ziffern haben (alles über 6 wird abgeschnitten).

  4. Gebrochene Stunden und Minuten werden nicht unterstützt.

Beispiele

>>> from datetime import time
>>> time.fromisoformat('04:23:01')
datetime.time(4, 23, 1)
>>> time.fromisoformat('T04:23:01')
datetime.time(4, 23, 1)
>>> time.fromisoformat('T042301')
datetime.time(4, 23, 1)
>>> time.fromisoformat('04:23:01.000384')
datetime.time(4, 23, 1, 384)
>>> time.fromisoformat('04:23:01,000384')
datetime.time(4, 23, 1, 384)
>>> time.fromisoformat('04:23:01+04:00')
datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))
>>> time.fromisoformat('04:23:01Z')
datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)
>>> time.fromisoformat('04:23:01+00:00')
datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)

Hinzugefügt in Version 3.7.

Geändert in Version 3.11: Zuvor unterstützte diese Methode nur Formate, die von time.isoformat() ausgegeben werden konnten.

classmethod time.strptime(date_string, format)

Gibt eine time zurück, die date_string entspricht, geparst gemäß format.

Wenn format keine Mikrosekunden- oder Zeitzoneninformationen enthält, ist dies gleichbedeutend mit

time(*(time.strptime(date_string, format)[3:6]))

ValueError wird ausgelöst, wenn date_string und format nicht von time.strptime() geparst werden können oder wenn es einen Wert zurückgibt, der kein Zeit-Tupel ist. Siehe auch Verhalten von strftime() und strptime() und time.fromisoformat().

Hinzugefügt in Version 3.14.

Instanzmethoden

time.replace(hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)

Gibt ein neues time mit den gleichen Werten zurück, aber mit angegebenen Parametern aktualisiert. Beachten Sie, dass tzinfo=None angegeben werden kann, um ein naives time aus einem "aware" time zu erstellen, ohne die Zeitdaten zu konvertieren.

time-Objekte werden auch von der generischen Funktion copy.replace() unterstützt.

Geändert in Version 3.6: Parameter fold hinzugefügt.

time.isoformat(timespec='auto')

Gibt eine Zeichenkette zurück, die die Uhrzeit im ISO 8601-Format darstellt, eine von

Das optionale Argument timespec gibt die Anzahl der zusätzlichen Zeitkomponenten an, die enthalten werden sollen (Standard ist 'auto'). Es kann einer der folgenden Werte sein:

  • 'auto': Wie 'seconds', wenn microsecond 0 ist, wie 'microseconds' sonst.

  • 'hours': Schließt die hour im zweistelligen HH-Format ein.

  • 'minutes': Schließt hour und minute im HH:MM-Format ein.

  • 'seconds': Schließt hour, minute und second im HH:MM:SS-Format ein.

  • 'milliseconds': Schließt die vollständige Uhrzeit ein, schneidet aber den Bruchteil der Sekunde auf Millisekunden ab. HH:MM:SS.sss-Format.

  • 'microseconds': Schließt die vollständige Uhrzeit im HH:MM:SS.ffffff-Format ein.

Hinweis

Ausgeschlossene Zeitkomponenten werden abgeschnitten, nicht gerundet.

ValueError wird bei einem ungültigen timespec-Argument ausgelöst.

Beispiel

>>> from datetime import time
>>> time(hour=12, minute=34, second=56, microsecond=123456).isoformat(timespec='minutes')
'12:34'
>>> dt = time(hour=12, minute=34, second=56, microsecond=0)
>>> dt.isoformat(timespec='microseconds')
'12:34:56.000000'
>>> dt.isoformat(timespec='auto')
'12:34:56'

Geändert in Version 3.6: Der Parameter timespec wurde hinzugefügt.

time.__str__()

Für eine Uhrzeit t ist str(t) gleichbedeutend mit t.isoformat().

time.strftime(format)

Gibt eine Zeichenkette zurück, die die Uhrzeit darstellt, gesteuert durch eine explizite Formatzeichenkette. Siehe auch Verhalten von strftime() und strptime() und time.isoformat().

time.__format__(format)

Wie time.strftime(). Dies ermöglicht die Angabe einer Formatzeichenkette für ein time-Objekt in formatierten Zeichenketten-Literalen und bei Verwendung von str.format(). Siehe auch Verhalten von strftime() und strptime() und time.isoformat().

time.utcoffset()

Wenn tzinfo None ist, wird None zurückgegeben, andernfalls wird self.tzinfo.utcoffset(None) zurückgegeben, und es wird eine Ausnahme ausgelöst, wenn letzteres nicht None oder ein timedelta-Objekt mit einer Magnitude kleiner als ein Tag zurückgibt.

Geändert in Version 3.7: Der UTC-Offset ist nicht mehr auf eine ganze Anzahl von Minuten beschränkt.

time.dst()

Wenn tzinfo None ist, wird None zurückgegeben, andernfalls wird self.tzinfo.dst(None) zurückgegeben, und es wird eine Ausnahme ausgelöst, wenn letzteres nicht None oder ein timedelta-Objekt mit einer Magnitude kleiner als ein Tag zurückgibt.

Geändert in Version 3.7: Der DST-Offset ist nicht mehr auf eine ganze Anzahl von Minuten beschränkt.

time.tzname()

Wenn tzinfo None ist, wird None zurückgegeben, andernfalls wird self.tzinfo.tzname(None) zurückgegeben, oder es wird eine Ausnahme ausgelöst, wenn letzteres nicht None oder ein String-Objekt zurückgibt.

Anwendungsbeispiele: time

Beispiele für die Arbeit mit einem time-Objekt

>>> from datetime import time, tzinfo, timedelta
>>> class TZ1(tzinfo):
...     def utcoffset(self, dt):
...         return timedelta(hours=1)
...     def dst(self, dt):
...         return timedelta(0)
...     def tzname(self,dt):
...         return "+01:00"
...     def  __repr__(self):
...         return f"{self.__class__.__name__}()"
...
>>> t = time(12, 10, 30, tzinfo=TZ1())
>>> t
datetime.time(12, 10, 30, tzinfo=TZ1())
>>> t.isoformat()
'12:10:30+01:00'
>>> t.dst()
datetime.timedelta(0)
>>> t.tzname()
'+01:00'
>>> t.strftime("%H:%M:%S %Z")
'12:10:30 +01:00'
>>> 'The {} is {:%H:%M}.'.format("time", t)
'The time is 12:10.'

tzinfo-Objekte

class datetime.tzinfo

Dies ist eine abstrakte Basisklasse, was bedeutet, dass diese Klasse nicht direkt instanziiert werden sollte. Definieren Sie eine Unterklasse von tzinfo, um Informationen über eine bestimmte Zeitzone zu erfassen.

Eine Instanz von (einer konkreten Unterklasse von) tzinfo kann an die Konstruktoren für datetime und time-Objekte übergeben werden. Letztere Objekte betrachten ihre Attribute als in lokaler Zeit, und das tzinfo-Objekt unterstützt Methoden, die den Offset der Lokalzeit von UTC, den Namen der Zeitzone und den DST-Offset offenlegen, alles relativ zu einem Datum oder Zeitobjekt, das ihnen übergeben wird.

Sie müssen eine konkrete Unterklasse ableiten und (zumindest) Implementierungen der Standardmethoden von tzinfo bereitstellen, die von den von Ihnen verwendeten datetime-Methoden benötigt werden. Das Modul datetime stellt timezone bereit, eine einfache konkrete Unterklasse von tzinfo, die Zeitzonen mit festem Offset von UTC wie UTC selbst oder nordamerikanische EST und EDT darstellen kann.

Spezielle Anforderung für das Pickling: Eine tzinfo-Unterklasse muss eine __init__()-Methode haben, die ohne Argumente aufgerufen werden kann, andernfalls kann sie gepickelt, aber möglicherweise nicht wieder entpickelt werden. Dies ist eine technische Anforderung, die in Zukunft möglicherweise gelockert wird.

Eine konkrete Unterklasse von tzinfo muss möglicherweise die folgenden Methoden implementieren. Welche Methoden genau benötigt werden, hängt von der Verwendung von "aware" (zeitzoneninformierten) datetime-Objekten ab. Im Zweifelsfall implementieren Sie einfach alle.

tzinfo.utcoffset(dt)

Gibt den Offset der Lokalzeit von UTC zurück, als timedelta-Objekt, das östlich von UTC positiv ist. Wenn die Lokalzeit westlich von UTC liegt, sollte dies negativ sein.

Dies repräsentiert den *Gesamt*-Offset von UTC; zum Beispiel, wenn ein tzinfo-Objekt sowohl Zeitzonen- als auch DST-Anpassungen darstellt, sollte utcoffset() ihre Summe zurückgeben. Wenn der UTC-Offset nicht bekannt ist, geben Sie None zurück. Andernfalls muss der zurückgegebene Wert ein timedelta-Objekt sein, das streng zwischen -timedelta(hours=24) und timedelta(hours=24) liegt (die Magnitude des Offsets muss kleiner als ein Tag sein). Die meisten Implementierungen von utcoffset() werden wahrscheinlich wie eine der beiden folgenden aussehen:

return CONSTANT                 # fixed-offset class
return CONSTANT + self.dst(dt)  # daylight-aware class

Wenn utcoffset() nicht None zurückgibt, sollte dst() auch nicht None zurückgeben.

Die Standardimplementierung von utcoffset() löst NotImplementedError aus.

Geändert in Version 3.7: Der UTC-Offset ist nicht mehr auf eine ganze Anzahl von Minuten beschränkt.

tzinfo.dst(dt)

Gibt die Sommerzeit (DST)-Anpassung als timedelta-Objekt oder None zurück, wenn DST-Informationen nicht bekannt sind.

Gibt timedelta(0) zurück, wenn DST nicht in Kraft ist. Wenn DST in Kraft ist, geben Sie den Offset als timedelta-Objekt zurück (siehe utcoffset() für Details). Beachten Sie, dass der DST-Offset, falls zutreffend, bereits zum UTC-Offset addiert wurde, der von utcoffset() zurückgegeben wird. Daher muss dst() nicht konsultiert werden, es sei denn, Sie möchten DST-Informationen separat erhalten. Zum Beispiel ruft datetime.timetuple() das tzinfo-Attribut des datetime-Objekts auf, um zu bestimmen, wie das Flag tm_isdst gesetzt werden soll, und tzinfo.fromutc() ruft dst() auf, um DST-Änderungen beim Überqueren von Zeitzonen zu berücksichtigen.

Eine Instanz tz einer tzinfo-Unterklasse, die sowohl Standard- als auch Sommerzeiten modelliert, muss in diesem Sinne konsistent sein:

tz.utcoffset(dt) - tz.dst(dt)

muss für jedes datetime-Objekt dt mit dt.tzinfo == tz dasselbe Ergebnis liefern. Für vernünftige tzinfo-Unterklassen ergibt dieser Ausdruck den "Standard-Offset" der Zeitzone, der nicht vom Datum oder der Uhrzeit abhängen sollte, sondern nur vom geografischen Standort. Die Implementierung von datetime.astimezone() beruht darauf, kann aber keine Verstöße erkennen; es liegt in der Verantwortung des Programmierers, dies sicherzustellen. Wenn eine tzinfo-Unterklasse dies nicht garantieren kann, kann sie möglicherweise die Standardimplementierung von tzinfo.fromutc() überschreiben, um trotzdem korrekt mit astimezone() zu arbeiten.

Die meisten Implementierungen von dst() werden wahrscheinlich wie eine der beiden folgenden aussehen:

def dst(self, dt):
    # a fixed-offset class:  doesn't account for DST
    return timedelta(0)

oder

def dst(self, dt):
    # Code to set dston and dstoff to the time zone's DST
    # transition times based on the input dt.year, and expressed
    # in standard local time.

    if dston <= dt.replace(tzinfo=None) < dstoff:
        return timedelta(hours=1)
    else:
        return timedelta(0)

Die Standardimplementierung von dst() löst NotImplementedError aus.

Geändert in Version 3.7: Der DST-Offset ist nicht mehr auf eine ganze Anzahl von Minuten beschränkt.

tzinfo.tzname(dt)

Gibt den Zeitzonennamen zurück, der dem datetime-Objekt dt entspricht, als Zeichenkette. Nichts über Zeichenkettennamen ist vom Modul datetime definiert, und es gibt keine Anforderung, dass es etwas Bestimmtes bedeutet. Zum Beispiel sind "GMT", "UTC", "-500", "-5:00", "EDT", "US/Eastern", "America/New York" alles gültige Antworten. Geben Sie None zurück, wenn ein Zeichenkettenname nicht bekannt ist. Beachten Sie, dass dies eine Methode und keine feste Zeichenkette ist, hauptsächlich weil einige tzinfo-Unterklassen je nach dem spezifischen Wert von dt, der übergeben wird, unterschiedliche Namen zurückgeben möchten, insbesondere wenn die tzinfo-Klasse die Sommerzeit berücksichtigt.

Die Standardimplementierung von tzname() löst NotImplementedError aus.

Diese Methoden werden von einem datetime- oder time-Objekt aufgerufen, als Reaktion auf ihre gleichnamigen Methoden. Ein datetime-Objekt übergibt sich selbst als Argument, und ein time-Objekt übergibt None als Argument. Die Methoden einer tzinfo-Unterklasse sollten daher darauf vorbereitet sein, ein dt-Argument von None oder von der Klasse datetime zu akzeptieren.

Wenn None übergeben wird, obliegt es dem Klassendesigner zu entscheiden, wie am besten darauf zu reagieren ist. Zum Beispiel ist die Rückgabe von None angemessen, wenn die Klasse angeben möchte, dass Zeitobjekte nicht an den tzinfo-Protokollen teilnehmen. Es kann für utcoffset(None) nützlicher sein, den Standard-UTC-Offset zurückzugeben, da es keine andere Konvention gibt, um den Standard-Offset zu ermitteln.

Wenn ein datetime-Objekt als Antwort auf eine datetime-Methode übergeben wird, ist dt.tzinfo dasselbe Objekt wie self. tzinfo-Methoden können sich darauf verlassen, es sei denn, Benutzercode ruft tzinfo-Methoden direkt auf. Die Absicht ist, dass die tzinfo-Methoden dt als lokale Zeit interpretieren und sich keine Sorgen um Objekte in anderen Zeitzonen machen müssen.

Es gibt noch eine weitere tzinfo-Methode, die eine Unterklasse möglicherweise überschreiben möchte

tzinfo.fromutc(dt)

Diese wird von der Standardimplementierung von datetime.astimezone() aufgerufen. Wenn von dort aufgerufen, ist dt.tzinfo self, und die Datums- und Zeitdaten von dt sind als UTC-Zeit anzusehen. Der Zweck von fromutc() ist es, die Datums- und Zeitdaten anzupassen und ein äquivalentes Datum und eine äquivalente Zeit in der lokalen Zeit von self zurückzugeben.

Die meisten tzinfo-Unterklassen sollten in der Lage sein, die Standardimplementierung von fromutc() ohne Probleme zu erben. Sie ist stark genug, um Zeitzonen mit festem Offset zu verarbeiten, sowie Zeitzonen, die sowohl die Standard- als auch die Sommerzeit berücksichtigen, und letztere auch dann, wenn sich die Sommerzeit-Übergangszeiten in verschiedenen Jahren unterscheiden. Ein Beispiel für eine Zeitzone, die die Standardimplementierung von fromutc() möglicherweise nicht in allen Fällen korrekt behandelt, ist eine, bei der der Standard-Offset (von UTC) vom spezifischen übergebenen Datum und der übergebenen Zeit abhängt, was aus politischen Gründen vorkommen kann. Die Standardimplementierungen von astimezone() und fromutc() liefern möglicherweise nicht das gewünschte Ergebnis, wenn das Ergebnis eine der Stunden ist, die den Moment des Wandels des Standard-Offsets umspannen.

Unter Auslassung von Code für Fehlerfälle verhält sich die Standardimplementierung von fromutc() wie

def fromutc(self, dt):
    # raise ValueError error if dt.tzinfo is not self
    dtoff = dt.utcoffset()
    dtdst = dt.dst()
    # raise ValueError if dtoff is None or dtdst is None
    delta = dtoff - dtdst  # this is self's standard offset
    if delta:
        dt += delta   # convert to standard local time
        dtdst = dt.dst()
        # raise ValueError if dtdst is None
    if dtdst:
        return dt + dtdst
    else:
        return dt

In der folgenden Datei tzinfo_examples.py finden Sie einige Beispiele für tzinfo-Klassen

from datetime import tzinfo, timedelta, datetime

ZERO = timedelta(0)
HOUR = timedelta(hours=1)
SECOND = timedelta(seconds=1)

# A class capturing the platform's idea of local time.
# (May result in wrong values on historical times in
#  timezones where UTC offset and/or the DST rules had
#  changed in the past.)
import time as _time

STDOFFSET = timedelta(seconds = -_time.timezone)
if _time.daylight:
    DSTOFFSET = timedelta(seconds = -_time.altzone)
else:
    DSTOFFSET = STDOFFSET

DSTDIFF = DSTOFFSET - STDOFFSET

class LocalTimezone(tzinfo):

    def fromutc(self, dt):
        assert dt.tzinfo is self
        stamp = (dt - datetime(1970, 1, 1, tzinfo=self)) // SECOND
        args = _time.localtime(stamp)[:6]
        dst_diff = DSTDIFF // SECOND
        # Detect fold
        fold = (args == _time.localtime(stamp - dst_diff))
        return datetime(*args, microsecond=dt.microsecond,
                        tzinfo=self, fold=fold)

    def utcoffset(self, dt):
        if self._isdst(dt):
            return DSTOFFSET
        else:
            return STDOFFSET

    def dst(self, dt):
        if self._isdst(dt):
            return DSTDIFF
        else:
            return ZERO

    def tzname(self, dt):
        return _time.tzname[self._isdst(dt)]

    def _isdst(self, dt):
        tt = (dt.year, dt.month, dt.day,
              dt.hour, dt.minute, dt.second,
              dt.weekday(), 0, 0)
        stamp = _time.mktime(tt)
        tt = _time.localtime(stamp)
        return tt.tm_isdst > 0

Local = LocalTimezone()


# A complete implementation of current DST rules for major US time zones.

def first_sunday_on_or_after(dt):
    days_to_go = 6 - dt.weekday()
    if days_to_go:
        dt += timedelta(days_to_go)
    return dt


# US DST Rules
#
# This is a simplified (i.e., wrong for a few cases) set of rules for US
# DST start and end times. For a complete and up-to-date set of DST rules
# and timezone definitions, visit the Olson Database (or try pytz):
# http://www.twinsun.com/tz/tz-link.htm
# https://sourceforge.net/projects/pytz/ (might not be up-to-date)
#
# In the US, since 2007, DST starts at 2am (standard time) on the second
# Sunday in March, which is the first Sunday on or after Mar 8.
DSTSTART_2007 = datetime(1, 3, 8, 2)
# and ends at 2am (DST time) on the first Sunday of Nov.
DSTEND_2007 = datetime(1, 11, 1, 2)
# From 1987 to 2006, DST used to start at 2am (standard time) on the first
# Sunday in April and to end at 2am (DST time) on the last
# Sunday of October, which is the first Sunday on or after Oct 25.
DSTSTART_1987_2006 = datetime(1, 4, 1, 2)
DSTEND_1987_2006 = datetime(1, 10, 25, 2)
# From 1967 to 1986, DST used to start at 2am (standard time) on the last
# Sunday in April (the one on or after April 24) and to end at 2am (DST time)
# on the last Sunday of October, which is the first Sunday
# on or after Oct 25.
DSTSTART_1967_1986 = datetime(1, 4, 24, 2)
DSTEND_1967_1986 = DSTEND_1987_2006

def us_dst_range(year):
    # Find start and end times for US DST. For years before 1967, return
    # start = end for no DST.
    if 2006 < year:
        dststart, dstend = DSTSTART_2007, DSTEND_2007
    elif 1986 < year < 2007:
        dststart, dstend = DSTSTART_1987_2006, DSTEND_1987_2006
    elif 1966 < year < 1987:
        dststart, dstend = DSTSTART_1967_1986, DSTEND_1967_1986
    else:
        return (datetime(year, 1, 1), ) * 2

    start = first_sunday_on_or_after(dststart.replace(year=year))
    end = first_sunday_on_or_after(dstend.replace(year=year))
    return start, end


class USTimeZone(tzinfo):

    def __init__(self, hours, reprname, stdname, dstname):
        self.stdoffset = timedelta(hours=hours)
        self.reprname = reprname
        self.stdname = stdname
        self.dstname = dstname

    def __repr__(self):
        return self.reprname

    def tzname(self, dt):
        if self.dst(dt):
            return self.dstname
        else:
            return self.stdname

    def utcoffset(self, dt):
        return self.stdoffset + self.dst(dt)

    def dst(self, dt):
        if dt is None or dt.tzinfo is None:
            # An exception may be sensible here, in one or both cases.
            # It depends on how you want to treat them.  The default
            # fromutc() implementation (called by the default astimezone()
            # implementation) passes a datetime with dt.tzinfo is self.
            return ZERO
        assert dt.tzinfo is self
        start, end = us_dst_range(dt.year)
        # Can't compare naive to aware objects, so strip the timezone from
        # dt first.
        dt = dt.replace(tzinfo=None)
        if start + HOUR <= dt < end - HOUR:
            # DST is in effect.
            return HOUR
        if end - HOUR <= dt < end:
            # Fold (an ambiguous hour): use dt.fold to disambiguate.
            return ZERO if dt.fold else HOUR
        if start <= dt < start + HOUR:
            # Gap (a non-existent hour): reverse the fold rule.
            return HOUR if dt.fold else ZERO
        # DST is off.
        return ZERO

    def fromutc(self, dt):
        assert dt.tzinfo is self
        start, end = us_dst_range(dt.year)
        start = start.replace(tzinfo=self)
        end = end.replace(tzinfo=self)
        std_time = dt + self.stdoffset
        dst_time = std_time + HOUR
        if end <= dst_time < end + HOUR:
            # Repeated hour
            return std_time.replace(fold=1)
        if std_time < start or dst_time >= end:
            # Standard time
            return std_time
        if start <= std_time < end - HOUR:
            # Daylight saving time
            return dst_time


Eastern  = USTimeZone(-5, "Eastern",  "EST", "EDT")
Central  = USTimeZone(-6, "Central",  "CST", "CDT")
Mountain = USTimeZone(-7, "Mountain", "MST", "MDT")
Pacific  = USTimeZone(-8, "Pacific",  "PST", "PDT")

Beachten Sie, dass es zweimal im Jahr in einer tzinfo-Unterklasse, die sowohl die Standard- als auch die Sommerzeit berücksichtigt, zu unvermeidlichen Feinheiten kommt, und zwar zu den Sommerzeit-Übergangspunkten. Konkret betrachten wir Eastern US (UTC -0500), wo die EDT am Minute nach 1:59 (EST) am zweiten Sonntag im März beginnt und am Minute nach 1:59 (EDT) am ersten Sonntag im November endet

  UTC   3:MM  4:MM  5:MM  6:MM  7:MM  8:MM
  EST  22:MM 23:MM  0:MM  1:MM  2:MM  3:MM
  EDT  23:MM  0:MM  1:MM  2:MM  3:MM  4:MM

start  22:MM 23:MM  0:MM  1:MM  3:MM  4:MM

  end  23:MM  0:MM  1:MM  1:MM  2:MM  3:MM

Wenn die Sommerzeit beginnt (die "Start"-Zeile), springt die lokale Wanduhr von 1:59 auf 3:00. Eine Wandzeit der Form 2:MM ist an diesem Tag nicht wirklich sinnvoll, daher liefert astimezone(Eastern) an dem Tag, an dem die Sommerzeit beginnt, kein Ergebnis mit hour == 2. Zum Beispiel erhalten wir beim Übergang im Frühjahr 2016

>>> from datetime import datetime, timezone
>>> from tzinfo_examples import HOUR, Eastern
>>> u0 = datetime(2016, 3, 13, 5, tzinfo=timezone.utc)
>>> for i in range(4):
...     u = u0 + i*HOUR
...     t = u.astimezone(Eastern)
...     print(u.time(), 'UTC =', t.time(), t.tzname())
...
05:00:00 UTC = 00:00:00 EST
06:00:00 UTC = 01:00:00 EST
07:00:00 UTC = 03:00:00 EDT
08:00:00 UTC = 04:00:00 EDT

Wenn die Sommerzeit endet (die "End"-Zeile), gibt es ein potenziell schlimmeres Problem: Es gibt eine Stunde, die in lokaler Wandzeit nicht eindeutig ausgedrückt werden kann: die letzte Stunde der Sommerzeit. In Eastern sind das Zeiten der Form 5:MM UTC an dem Tag, an dem die Sommerzeit endet. Die lokale Wanduhr springt von 1:59 (Sommerzeit) zurück auf 1:00 (Standardzeit). Lokale Zeiten der Form 1:MM sind mehrdeutig. astimezone() ahmt das Verhalten der lokalen Uhr nach, indem es zwei aufeinanderfolgende UTC-Stunden in dieselbe lokale Stunde abbildet. Im Eastern-Beispiel werden UTC-Zeiten der Form 5:MM und 6:MM bei der Umwandlung nach Eastern beide auf 1:MM abgebildet, aber frühere Zeiten haben das Attribut fold auf 0 gesetzt und spätere Zeiten haben es auf 1 gesetzt. Zum Beispiel erhalten wir beim Übergang im Herbst 2016

>>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc)
>>> for i in range(4):
...     u = u0 + i*HOUR
...     t = u.astimezone(Eastern)
...     print(u.time(), 'UTC =', t.time(), t.tzname(), t.fold)
...
04:00:00 UTC = 00:00:00 EDT 0
05:00:00 UTC = 01:00:00 EDT 0
06:00:00 UTC = 01:00:00 EST 1
07:00:00 UTC = 02:00:00 EST 0

Beachten Sie, dass die datetime-Instanzen, die sich nur durch den Wert des fold-Attributs unterscheiden, bei Vergleichen als gleich betrachtet werden.

Anwendungen, die Wandzeit-Mehrdeutigkeiten nicht ertragen können, sollten explizit den Wert des fold-Attributs prüfen oder die Verwendung von hybriden tzinfo-Unterklassen vermeiden; es gibt keine Mehrdeutigkeiten bei der Verwendung von timezone oder einer anderen tzinfo-Unterklasse mit festem Offset (wie z. B. einer Klasse, die nur EST (fester Offset -5 Stunden) oder nur EDT (fester Offset -4 Stunden) repräsentiert).

Siehe auch

zoneinfo

Das Modul datetime hat eine einfache timezone-Klasse (zur Behandlung beliebiger fester Offsets von UTC) und ihr Attribut timezone.utc (eine UTC timezone-Instanz).

zoneinfo bringt die *IANA Time Zone Database* (auch bekannt als Olson-Datenbank) nach Python, und ihre Verwendung wird empfohlen.

IANA Time Zone Database

Die Time Zone Database (oft tz, tzdata oder zoneinfo genannt) enthält Code und Daten, die die Geschichte der lokalen Zeit für viele repräsentative Orte auf der ganzen Welt darstellen. Sie wird periodisch aktualisiert, um Änderungen von politischen Gremien an Zeitzonengrenzen, UTC-Offsets und Regeln für die Sommerzeit widerzuspiegeln.

timezone-Objekte

Die Klasse timezone ist eine Unterklasse von tzinfo, von der jede Instanz eine Zeitzone repräsentiert, die durch einen festen Offset von UTC definiert ist.

Objekte dieser Klasse können nicht verwendet werden, um Zeitzoneninformationen für Orte darzustellen, an denen zu verschiedenen Zeiten des Jahres unterschiedliche Offsets verwendet werden oder an denen historische Änderungen an der Zivilzeit vorgenommen wurden.

class datetime.timezone(offset, name=None)

Das Argument offset muss als timedelta-Objekt angegeben werden, das die Differenz zwischen der lokalen Zeit und UTC darstellt. Es muss streng zwischen -timedelta(hours=24) und timedelta(hours=24) liegen, andernfalls wird ValueError ausgelöst.

Das Argument name ist optional. Wenn es angegeben ist, muss es eine Zeichenkette sein, die als Wert verwendet wird, der von der Methode datetime.tzname() zurückgegeben wird.

Hinzugefügt in Version 3.2.

Geändert in Version 3.7: Der UTC-Offset ist nicht mehr auf eine ganze Anzahl von Minuten beschränkt.

timezone.utcoffset(dt)

Gibt den festen Wert zurück, der beim Erstellen der timezone-Instanz angegeben wurde.

Das Argument dt wird ignoriert. Der Rückgabewert ist eine timedelta-Instanz, die der Differenz zwischen der lokalen Zeit und UTC entspricht.

Geändert in Version 3.7: Der UTC-Offset ist nicht mehr auf eine ganze Anzahl von Minuten beschränkt.

timezone.tzname(dt)

Gibt den festen Wert zurück, der beim Erstellen der timezone-Instanz angegeben wurde.

Wenn name im Konstruktor nicht angegeben wurde, wird der Name, der von tzname(dt) zurückgegeben wird, aus dem Wert des offset generiert. Wenn offset timedelta(0) ist, ist der Name "UTC", andernfalls ist es eine Zeichenkette im Format UTC±HH:MM, wobei ± das Vorzeichen von offset ist, HH und MM zwei Ziffern von offset.hours und offset.minutes sind.

Geändert in Version 3.6: Der aus offset=timedelta(0) generierte Name ist jetzt schlicht 'UTC' und nicht 'UTC+00:00'.

timezone.dst(dt)

Gibt immer None zurück.

timezone.fromutc(dt)

Gibt dt + offset zurück. Das Argument dt muss eine bewusste datetime-Instanz sein, mit tzinfo auf self gesetzt.

Klassenattribute

timezone.utc

Die UTC-Zeitzone, timezone(timedelta(0)).

strftime()- und strptime()-Verhalten

date-, datetime- und time-Objekte unterstützen alle eine Methode strftime(format), um eine Zeit unter der Kontrolle eines expliziten Formatstrings zu erzeugen.

Umgekehrt erstellen die Klassenmethoden date.strptime(), datetime.strptime() und time.strptime() ein Objekt aus einem String, der die Zeit darstellt, und einem entsprechenden Formatstring.

Die folgende Tabelle bietet einen Vergleich von strftime() und strptime()

strftime

strptime

Verwendung

Objekt nach einem gegebenen Format in eine Zeichenkette umwandeln

Eine Zeichenkette anhand eines entsprechenden Formats in ein Objekt parsen

Typ der Methode

Instanzmethode

Klassenmethode

Signatur

strftime(format)

strptime(date_string, format)

Formatcodes für strftime() und strptime()

Diese Methoden akzeptieren Formatcodes, die zum Parsen und Formatieren von Daten verwendet werden können

>>> datetime.strptime('31/01/22 23:59:59.999999',
...                   '%d/%m/%y %H:%M:%S.%f')
datetime.datetime(2022, 1, 31, 23, 59, 59, 999999)
>>> _.strftime('%a %d %b %Y, %I:%M%p')
'Mon 31 Jan 2022, 11:59PM'

Die folgende Liste enthält alle Formatcodes, die der C89-Standard vorschreibt und die auf allen Plattformen mit einer Standard-C-Implementierung funktionieren.

Direktive

Bedeutung

Beispiel

Hinweise

%a

Wochentag als abgekürzter Name der Locale.
Son, Mon, …, Sat (en_US);
So, Mo, …, Sa (de_DE)

(1)

%A

Wochentag als vollständiger Name der Locale.
Sunday, Monday, …, Saturday (en_US);
Sonntag, Montag, …, Samstag (de_DE)

(1)

%w

Wochentag als Dezimalzahl, wobei 0 Sonntag und 6 Samstag ist.

0, 1, …, 6

%d

Tag des Monats als null-aufgefüllte Dezimalzahl.

01, 02, …, 31

(9)

%b

Monat als abgekürzter Name der Locale.
Jan, Feb, …, Dez (en_US);
Jan, Feb, …, Dez (de_DE)

(1)

%B

Monat als vollständiger Name der Locale.
January, February, …, December (en_US);
Januar, Februar, …, Dezember (de_DE)

(1)

%m

Monat als null-aufgefüllte Dezimalzahl.

01, 02, …, 12

(9)

%y

Jahr ohne Jahrhundert als null-aufgefüllte Dezimalzahl.

00, 01, …, 99

(9)

%Y

Jahr mit Jahrhundert als Dezimalzahl.

0001, 0002, …, 2013, 2014, …, 9998, 9999

(2)

%H

Stunde (24-Stunden-Format) als null-aufgefüllte Dezimalzahl.

00, 01, …, 23

(9)

%I

Stunde (12-Stunden-Format) als null-aufgefüllte Dezimalzahl.

01, 02, …, 12

(9)

%p

Locale-entsprechende Bezeichnung für AM oder PM.
AM, PM (en_US);
am, pm (de_DE)

(1), (3)

%M

Minute als null-aufgefüllte Dezimalzahl.

00, 01, …, 59

(9)

%S

Sekunde als null-aufgefüllte Dezimalzahl.

00, 01, …, 59

(4), (9)

%f

Mikrosekunde als Dezimalzahl, 6-stellig null-aufgefüllt.

000000, 000001, …, 999999

(5)

%z

UTC-Offset im Format ±HHMM[SS[.ffffff]] (leere Zeichenkette, wenn das Objekt naiv ist).

(leer), +0000, -0400, +1030, +063415, -030712.345216

(6)

%Z

Zeitzonenname (leere Zeichenkette, wenn das Objekt naiv ist).

(leer), UTC, GMT

(6)

%j

Tag des Jahres als null-aufgefüllte Dezimalzahl.

001, 002, …, 366

(9)

%U

Wochennummer des Jahres (Sonntag als erster Tag der Woche) als null-aufgefüllte Dezimalzahl. Alle Tage in einem neuen Jahr vor dem ersten Sonntag werden der Woche 0 zugeordnet.

00, 01, …, 53

(7), (9)

%W

Wochennummer des Jahres (Montag als erster Tag der Woche) als null-aufgefüllte Dezimalzahl. Alle Tage in einem neuen Jahr vor dem ersten Montag werden der Woche 0 zugeordnet.

00, 01, …, 53

(7), (9)

%c

Locale-entsprechende Datums- und Zeitdarstellung.
Tue Aug 16 21:30:00 1988 (en_US);
Di 16 Aug 21:30:00 1988 (de_DE)

(1)

%x

Locale-entsprechende Datumsdarstellung.
08/16/88 (None);
08/16/1988 (en_US);
16.08.1988 (de_DE)

(1)

%X

Locale-entsprechende Zeitdarstellung.
21:30:00 (en_US);
21:30:00 (de_DE)

(1)

%%

Ein literales '%'-Zeichen.

%

Mehrere zusätzliche Direktiven, die nicht vom C89-Standard gefordert werden, sind zur Bequemlichkeit enthalten. Diese Parameter entsprechen alle ISO 8601-Datumsangaben.

Direktive

Bedeutung

Beispiel

Hinweise

%G

ISO 8601-Jahr mit Jahrhundert, das das Jahr repräsentiert, das den größten Teil der ISO-Woche (%V) enthält.

0001, 0002, …, 2013, 2014, …, 9998, 9999

(8)

%u

ISO 8601-Wochentag als Dezimalzahl, wobei 1 Montag ist.

1, 2, …, 7

%V

ISO 8601-Woche als Dezimalzahl mit Montag als erstem Tag der Woche. Woche 01 ist die Woche, die den 4. Januar enthält.

01, 02, …, 53

(8), (9)

%:z

UTC-Offset im Format ±HH:MM[:SS[.ffffff]] (leere Zeichenkette, wenn das Objekt naiv ist).

(leer), +00:00, -04:00, +10:30, +06:34:15, -03:07:12.345216

(6)

Diese sind möglicherweise nicht auf allen Plattformen verfügbar, wenn sie mit der Methode strftime() verwendet werden. Die Direktiven für ISO 8601-Jahr und ISO 8601-Woche sind nicht austauschbar mit den oben genannten Direktiven für Jahr und Wochennummer. Das Aufrufen von strptime() mit unvollständigen oder mehrdeutigen ISO 8601-Direktiven löst einen ValueError aus.

Der vollständige Satz von unterstützten Formatcodes variiert je nach Plattform, da Python die strftime()-Funktion der C-Bibliothek der Plattform aufruft und plattformabhängige Abweichungen üblich sind. Um den vollständigen Satz von auf Ihrer Plattform unterstützten Formatcodes zu sehen, konsultieren Sie die Dokumentation von strftime(3). Es gibt auch Unterschiede zwischen Plattformen bei der Behandlung nicht unterstützter Formatbezeichner.

Hinzugefügt in Version 3.6: %G, %u und %V wurden hinzugefügt.

Hinzugefügt in Version 3.12: %:z wurde hinzugefügt.

Technische Details

Im Allgemeinen verhält sich d.strftime(fmt) ähnlich wie die Methode time.strftime(fmt, d.timetuple()) des Moduls time, obwohl nicht alle Objekte eine timetuple()-Methode unterstützen.

Für die Klassenmethode datetime.strptime() ist der Standardwert 1900-01-01T00:00:00.000: Alle Komponenten, die im Formatstring nicht angegeben sind, werden aus dem Standardwert übernommen. [4]

Die Verwendung von datetime.strptime(date_string, format) ist äquivalent zu

datetime(*(time.strptime(date_string, format)[0:6]))

außer wenn das Format Sub-Sekunden-Komponenten oder Zeitzonen-Offset-Informationen enthält, die in datetime.strptime unterstützt werden, aber von time.strptime verworfen werden.

Für time-Objekte sollten die Formatcodes für Jahr, Monat und Tag nicht verwendet werden, da time-Objekte keine solchen Werte haben. Wenn sie dennoch verwendet werden, werden 1900 für das Jahr und 1 für Monat und Tag eingesetzt.

Für date-Objekte sollten die Formatcodes für Stunden, Minuten, Sekunden und Mikrosekunden nicht verwendet werden, da date-Objekte keine solchen Werte haben. Wenn sie dennoch verwendet werden, werden diese mit 0 substituiert.

Aus demselben Grund ist die Handhabung von Formatstrings, die Unicode-Codepunkte enthalten, die nicht in der Zeichenkodierung der aktuellen Locale dargestellt werden können, ebenfalls plattformabhängig. Auf einigen Plattformen werden solche Codepunkte intakt in der Ausgabe beibehalten, während auf anderen strftime UnicodeError auslösen oder eine leere Zeichenkette zurückgeben kann.

Hinweise

  1. Da das Format von der aktuellen Locale abhängt, ist Vorsicht geboten, wenn Annahmen über den Ausgabewert getroffen werden. Die Reihenfolge der Felder variiert (z. B. "Monat/Tag/Jahr" gegenüber "Tag/Monat/Jahr"), und die Ausgabe kann Nicht-ASCII-Zeichen enthalten.

  2. Die Methode strptime() kann Jahre im vollen Bereich [1, 9999] parsen, aber Jahre < 1000 müssen auf 4 Ziffern null-aufgefüllt werden.

    Geändert in Version 3.2: In früheren Versionen war die Methode strftime() auf Jahre >= 1900 beschränkt.

    Geändert in Version 3.3: In Version 3.2 war die Methode strftime() auf Jahre >= 1000 beschränkt.

  3. Bei Verwendung mit der Methode strptime() beeinflusst die Direktive %p nur das Ausgabestundenfeld, wenn die Direktive %I zur Interpretation der Stunde verwendet wird.

  4. Im Gegensatz zum Modul time unterstützt das Modul datetime keine Schaltsekunden.

  5. Bei Verwendung mit der Methode strptime() akzeptiert die Direktive %f ein bis sechs Ziffern und füllt mit Nullen auf der rechten Seite auf. %f ist eine Erweiterung des Satzes von Formatzeichen im C-Standard (aber separat in datetime-Objekten implementiert und daher immer verfügbar).

  6. Für ein naives Objekt werden die Formatcodes %z, %:z und %Z durch leere Zeichenketten ersetzt.

    Für ein bewusstes Objekt

    %z

    utcoffset() wird in eine Zeichenkette der Form ±HHMM[SS[.ffffff]] umgewandelt, wobei HH eine 2-stellige Zeichenkette für die Anzahl der UTC-Offset-Stunden, MM eine 2-stellige Zeichenkette für die Anzahl der UTC-Offset-Minuten, SS eine 2-stellige Zeichenkette für die Anzahl der UTC-Offset-Sekunden und ffffff eine 6-stellige Zeichenkette für die Anzahl der UTC-Offset-Mikrosekunden ist. Der Teil ffffff wird weggelassen, wenn der Offset eine ganze Anzahl von Sekunden ist, und sowohl der Teil ffffff als auch der Teil SS werden weggelassen, wenn der Offset eine ganze Anzahl von Minuten ist. Wenn utcoffset() beispielsweise timedelta(hours=-3, minutes=-30) zurückgibt, wird %z durch die Zeichenkette '-0330' ersetzt.

    Geändert in Version 3.7: Der UTC-Offset ist nicht mehr auf eine ganze Anzahl von Minuten beschränkt.

    Geändert in Version 3.7: Wenn die Direktive %z der Methode strptime() übergeben wird, können die UTC-Offsets einen Doppelpunkt als Trennzeichen zwischen Stunden, Minuten und Sekunden haben. Zum Beispiel wird '+01:00:00' als Offset von einer Stunde geparst. Außerdem ist die Angabe von 'Z' identisch mit '+00:00'.

    %:z

    Verhält sich genau wie %z, fügt aber einen Doppelpunkt als Trennzeichen zwischen Stunden, Minuten und Sekunden hinzu.

    %Z

    In strftime() wird %Z durch eine leere Zeichenkette ersetzt, wenn tzname() None zurückgibt; andernfalls wird %Z durch den zurückgegebenen Wert ersetzt, der eine Zeichenkette sein muss.

    strptime() akzeptiert nur bestimmte Werte für %Z

    1. jeder Wert in time.tzname für die Locale Ihres Rechners

    2. die hartcodierten Werte UTC und GMT

    Jemand, der in Japan lebt, hat möglicherweise JST, UTC und GMT als gültige Werte, aber wahrscheinlich nicht EST. Für ungültige Werte wird ValueError ausgelöst.

    Geändert in Version 3.2: Wenn die %z Direktive an die strptime() Methode übergeben wird, wird ein bewusstes datetime Objekt erzeugt. Der tzinfo des Ergebnisses wird auf eine timezone Instanz gesetzt.

  7. Bei Verwendung mit der strptime() Methode werden %U und %W nur in Berechnungen verwendet, wenn der Wochentag und das Kalenderjahr (%Y) angegeben sind.

  8. Ähnlich wie %U und %W wird %V nur in Berechnungen verwendet, wenn der Wochentag und das ISO-Jahr (%G) in einem strptime() Formatstring angegeben sind. Beachten Sie auch, dass %G und %Y nicht austauschbar sind.

  9. Bei Verwendung mit der strptime() Methode ist die führende Null für die Formate %d, %m, %H, %I, %M, %S, %j, %U, %W und %V optional. Format %y erfordert eine führende Null.

  10. Beim Parsen eines Monats und Tages mit strptime(), geben Sie immer ein Jahr im Format an. Wenn der zu parsende Wert kein Jahr hat, fügen Sie ein explizites Dummy-Schaltjahr hinzu. Andernfalls wird Ihr Code eine Ausnahme auslösen, wenn er auf den Schalttag trifft, da das vom Parser verwendete Standardjahr kein Schaltjahr ist. Benutzer stoßen alle vier Jahre auf diesen Fehler...

    >>> month_day = "02/29"
>>> datetime.strptime(f"{month_day};1984", "%m/%d;%Y")  # No leap year bug.
datetime.datetime(1984, 2, 29, 0, 0)

    Veraltet seit Version 3.13, wird in Version 3.15 entfernt: strptime() Aufrufe mit einem Formatstring, der einen Tag des Monats ohne Jahr enthält, lösen jetzt eine DeprecationWarning aus. In 3.15 oder später können wir dies in einen Fehler ändern oder das Standardjahr in ein Schaltjahr ändern. Siehe gh-70647.

Fußnoten