time — Zeitzugriff und Zeitumrechnungen

---

Dieses Modul stellt verschiedene Funktionen rund um die Zeit bereit. Verwandte Funktionalität findest du auch in den Modulen datetime und calendar.

Dieses Modul ist zwar immer verfügbar, aber nicht alle Funktionen sind auf allen Plattformen verfügbar. Die meisten der in diesem Modul festgelegten Funktionen rufen Funktionen gleichen Namens aus der C-Bibliothek der Plattform auf. Manchmal ist es hilfreich, die Dokumentation der Plattform zu Rate zu ziehen, denn die Bedeutung dieser Funktionen unterscheidet sich von Plattform zu Plattform.

Einige Begriffe und Vereinbarungen sind hier zu erklären.

• Die Epoche ist der Zeitpunkt, an dem die Zeit beginnt, der Rückgabewert von time.gmtime(0). Auf allen Plattformen ist das der 1. Januar 1970, 00:00:00 (UTC).

• Der Begriff Sekunden seit der Epoche bezeichnet die Gesamtzahl der seit der Epoche verstrichenen Sekunden, üblicherweise ohne Schaltsekunden (leap seconds). Auf allen POSIX-konformen Plattformen sind Schaltsekunden aus dieser Summe ausgenommen.

• Die Funktionen in diesem Modul behandeln Datums- und Zeitangaben vor der Epoche (epoch) oder weit in der Zukunft möglicherweise nicht. Wo die Grenze in der Zukunft liegt, bestimmt die C-Bibliothek. Auf 32-Bit-Systemen liegt sie üblicherweise im Jahr 2038.

• Die Funktion strptime() kann zweistellige Jahreszahlen verarbeiten, wenn ihr der Formatbezeichner %y übergeben wird. Zweistellige Jahreszahlen werden nach den Standards POSIX und ISO C umgerechnet: Die Werte 69–99 werden auf 1969–1999 abgebildet, die Werte 0–68 auf 2000–2068.

• UTC ist Coordinated Universal Time und hat Greenwich Mean Time beziehungsweise GMT als Grundlage der internationalen Zeitmessung abgelöst. Das Akronym UTC ist kein Fehler, sondern folgt einem früheren, sprachunabhängigen Benennungsschema für Zeitstandards wie UT0, UT1 und UT2.

• DST steht für Daylight Saving Time, die Sommerzeit – eine Verschiebung der Zeitzone um (meist) eine Stunde während eines Teils des Jahres. Die DST-Regeln sind magisch (sie werden vom örtlichen Recht bestimmt) und können sich von Jahr zu Jahr ändern. Die C-Bibliothek hat eine Tabelle mit den örtlichen Regeln (der Flexibilität zuliebe wird sie oft aus einer Systemdatei gelesen) und ist in dieser Hinsicht die einzige Quelle Wahrer Weisheit.

• Die Genauigkeit der verschiedenen Echtzeitfunktionen kann geringer sein, als es die Einheit nahelegt, in der ihr Wert oder Argument angegeben ist. Auf den meisten Unix-Systemen „tickt“ die Uhr zum Beispiel nur 50- oder 100-mal pro Sekunde.

• Andererseits ist die Genauigkeit von time() und sleep() besser als die ihrer Unix-Gegenstücke: Zeiten werden als Gleitkommazahlen angegeben, time() gibt die genaueste verfügbare Zeit zurück (wo vorhanden über Unix gettimeofday()), und sleep() nimmt eine Zeit mit einem Bruchteil ungleich null an (wo vorhanden wird das über Unix select() umgesetzt).

• Der Zeitwert, den gmtime(), localtime() und strptime() zurückgeben und den asctime(), mktime() und strftime() annehmen, ist eine Folge aus 9 ganzen Zahlen. Die Rückgabewerte von gmtime(), localtime() und strptime() bieten außerdem Attributnamen für die einzelnen Felder.

  Eine Beschreibung dieser Objekte findest du unter struct_time.

  Geändert in Version 3.3: Der Typ struct_time wurde um die Attribute tm_gmtoff und tm_zone erweitert, sofern die Plattform die entsprechenden Member von struct tm unterstützt.

  Geändert in Version 3.6: Die Attribute tm_gmtoff und tm_zone von struct_time sind jetzt auf allen Plattformen verfügbar.

• Verwende die folgenden Funktionen, um zwischen Zeitdarstellungen umzurechnen:

  Von	Nach	Verwende
  Sekunden seit der Epoche	struct_time in UTC	gmtime()
  Sekunden seit der Epoche	struct_time in Ortszeit	localtime()
  struct_time in UTC	Sekunden seit der Epoche	calendar.timegm()
  struct_time in Ortszeit	Sekunden seit der Epoche	mktime()

Funktionen

time.asctime([time_tuple])

Wandelt ein Tupel oder ein struct_time, das eine Zeit so darstellt, wie gmtime() oder localtime() sie zurückgeben, in eine Zeichenkette der folgenden Form um: 'Sun Jun 20 23:21:05 1993'. Das Tagesfeld ist zwei Zeichen breit und wird bei einstelligem Tag mit einem Leerzeichen aufgefüllt, zum Beispiel: 'Wed Jun  9 04:26:40 1993'.

Ist time_tuple nicht angegeben, wird die aktuelle Zeit verwendet, wie localtime() sie zurückgibt. asctime() verwendet keine Angaben aus dem Gebietsschema.

Bemerkung

Anders als die C-Funktion gleichen Namens fügt asctime() keinen abschließenden Zeilenumbruch an.

time.pthread_getcpuclockid(thread_id, /)

Gibt die clk_id der threadspezifischen CPU-Zeit-Uhr für den angegebenen thread_id zurück.

Verwende threading.get_ident() oder das Attribut ident von threading.Thread-Objekten, um einen passenden Wert für thread_id zu bekommen.

Warnung

Ein ungültiger oder abgelaufener thread_id kann zu undefiniertem Verhalten führen, etwa zu einem Speicherzugriffsfehler.

Verfügbarkeit: Unix

Weitere Informationen stehen in der Man-Page zu pthread_getcpuclockid(3).

Added in version 3.7.

time.clock_getres(clk_id, /)

Gibt die Auflösung (Genauigkeit) der angegebenen Uhr clk_id zurück. Eine Liste der zulässigen Werte für clk_id steht unter Konstanten für Uhrenkennungen.

Verfügbarkeit: Unix.

Added in version 3.3.

time.clock_gettime(clk_id, /) → float

Gibt die Zeit der angegebenen Uhr clk_id zurück. Eine Liste der zulässigen Werte für clk_id steht unter Konstanten für Uhrenkennungen.

Verwende clock_gettime_ns(), um den Genauigkeitsverlust durch den Typ float zu vermeiden.

Verfügbarkeit: Unix.

Added in version 3.3.

time.clock_gettime_ns(clk_id, /) → int

Wie clock_gettime(), gibt die Zeit aber in Nanosekunden zurück.

Verfügbarkeit: Unix.

Added in version 3.7.

time.clock_settime(clk_id, time, /)

Setzt die Zeit der angegebenen Uhr clk_id. Derzeit ist CLOCK_REALTIME der einzige zulässige Wert für clk_id.

Verwende clock_settime_ns(), um den Genauigkeitsverlust durch den Typ float zu vermeiden.

Verfügbarkeit: Unix, not Android, not iOS.

Added in version 3.3.

Geändert in Version 3.15: Nimmt jede reelle Zahl als time an, nicht nur Ganz- oder Gleitkommazahlen.

time.clock_settime_ns(clk_id, time: int, /)

Wie clock_settime(), setzt die Zeit aber in Nanosekunden.

Verfügbarkeit: Unix, not Android, not iOS.

Added in version 3.7.

time.ctime(seconds=None, /)

Wandelt eine in Sekunden seit der Epoche (epoch) angegebene Zeit in eine Zeichenkette der Form 'Sun Jun 20 23:21:05 1993' um, die die Ortszeit darstellt. Das Tagesfeld ist zwei Zeichen breit und wird bei einstelligem Tag mit einem Leerzeichen aufgefüllt, zum Beispiel: 'Wed Jun  9 04:26:40 1993'.

Ist seconds nicht angegeben oder None, wird die aktuelle Zeit verwendet, wie time() sie zurückgibt. ctime(seconds) entspricht asctime(localtime(seconds)). ctime() verwendet keine Angaben aus dem Gebietsschema.

Geändert in Version 3.15: Nimmt jede reelle Zahl an, nicht nur Ganz- oder Gleitkommazahlen.

time.get_clock_info(name, /)

Liefert Informationen über die angegebene Uhr als Namensraumobjekt. Die unterstützten Uhrennamen und die zugehörigen Funktionen, die ihren Wert lesen, sind:

• 'monotonic': time.monotonic()

• 'perf_counter': time.perf_counter()

• 'process_time': time.process_time()

• 'thread_time': time.thread_time()

• 'time': time.time()

Das Ergebnis hat die folgenden Attribute:

• adjustable: True, wenn die Uhr so gesetzt werden kann, dass sie in der Zeit vor- oder zurückspringt, sonst False. Bezieht sich nicht auf allmähliche NTP-Ratenanpassungen.

• implementation: Der Name der zugrunde liegenden C-Funktion, mit der der Wert der Uhr geholt wird. Die möglichen Werte stehen unter Konstanten für Uhrenkennungen.

• monotonic: True, wenn die Uhr nicht zurückgehen kann, sonst False

• resolution: Die Auflösung der Uhr in Sekunden (float)

Added in version 3.3.

time.gmtime(seconds=None, /)

Wandelt eine in Sekunden seit der Epoche (epoch) angegebene Zeit in ein struct_time in UTC um, bei dem das dst-Flag immer null ist. Ist seconds nicht angegeben oder None, wird die aktuelle Zeit verwendet, wie time() sie zurückgibt. Bruchteile einer Sekunde werden nicht beachtet. Eine Beschreibung des struct_time-Objekts steht weiter oben. Die Umkehrung dieser Funktion ist calendar.timegm().

Geändert in Version 3.15: Nimmt jede reelle Zahl an, nicht nur Ganz- oder Gleitkommazahlen.

time.localtime(seconds=None, /)

Wie gmtime(), rechnet aber in die Ortszeit um. Ist seconds nicht angegeben oder None, wird die aktuelle Zeit verwendet, wie time() sie zurückgibt. Das dst-Flag wird auf 1 gesetzt, wenn für die angegebene Zeit die Sommerzeit gilt.

localtime() kann OverflowError auslösen, wenn der Zeitstempel außerhalb des Wertebereichs liegt, den die C-Funktionen localtime() oder gmtime() der Plattform unterstützen, und OSError, wenn localtime() oder gmtime() fehlschlägt. Häufig ist dieser Bereich auf die Jahre zwischen 1970 und 2038 beschränkt.

Geändert in Version 3.15: Nimmt jede reelle Zahl an, nicht nur Ganz- oder Gleitkommazahlen.

time.mktime(time_tuple, /)

Das ist die Umkehrfunktion von localtime(). Ihr Argument ist das struct_time oder das vollständige 9-Tupel (weil das dst-Flag gebraucht wird – verwende -1 als dst-Flag, wenn es unbekannt ist), das die Zeit in Ortszeit angibt, nicht in UTC. Sie gibt zur Verträglichkeit mit time() eine Gleitkommazahl zurück. Lässt sich der Eingabewert nicht als gültige Zeit darstellen, wird entweder OverflowError oder ValueError ausgelöst (je nachdem, ob Python oder die zugrunde liegenden C-Bibliotheken den ungültigen Wert abfangen). Das früheste Datum, für das sie eine Zeit erzeugen kann, hängt von der Plattform ab.

time.monotonic() → float

Gibt den Wert (in Sekundenbruchteilen) einer monotonen Uhr zurück, also einer Uhr, die nicht zurückgehen kann. Die Uhr wird von Aktualisierungen der Systemuhr nicht beeinflusst. Der Bezugspunkt des zurückgegebenen Werts ist undefiniert, deshalb ist nur die Differenz zwischen den Ergebnissen zweier Aufrufe gültig.

Uhr:

• Unter Windows werden QueryPerformanceCounter() und QueryPerformanceFrequency() aufgerufen.

• Unter macOS werden mach_absolute_time() und mach_timebase_info() aufgerufen.

• Unter HP-UX wird gethrtime() aufgerufen.

• Ruft clock_gettime(CLOCK_HIGHRES) auf, sofern vorhanden.

• Andernfalls wird clock_gettime(CLOCK_MONOTONIC) aufgerufen.

Verwende monotonic_ns(), um den Genauigkeitsverlust durch den Typ float zu vermeiden.

Added in version 3.3.

Geändert in Version 3.5: Die Funktion ist jetzt immer verfügbar, und die Uhr ist jetzt für alle Prozesse dieselbe.

Geändert in Version 3.10: Unter macOS ist die Uhr jetzt für alle Prozesse dieselbe.

time.monotonic_ns() → int

Wie monotonic(), gibt die Zeit aber in Nanosekunden zurück.

Added in version 3.7.

time.perf_counter() → float

Gibt den Wert (in Sekundenbruchteilen) eines Leistungszählers zurück, also einer Uhr mit der höchsten verfügbaren Auflösung, um eine kurze Dauer zu messen. Die Zeit, die während eines Schlafens verstreicht, ist eingeschlossen. Die Uhr ist für alle Prozesse dieselbe. Der Bezugspunkt des zurückgegebenen Werts ist undefiniert, deshalb ist nur die Differenz zwischen den Ergebnissen zweier Aufrufe gültig.

Verwendet unter CPython dieselbe Uhr wie time.monotonic() und ist eine monotone Uhr, also eine Uhr, die nicht zurückgehen kann.

Verwende perf_counter_ns(), um den Genauigkeitsverlust durch den Typ float zu vermeiden.

Added in version 3.3.

Geändert in Version 3.10: Unter Windows ist die Uhr jetzt für alle Prozesse dieselbe.

Geändert in Version 3.13: Verwendet dieselbe Uhr wie time.monotonic().

time.perf_counter_ns() → int

Wie perf_counter(), gibt die Zeit aber in Nanosekunden zurück.

Added in version 3.7.

time.process_time() → float

Gibt den Wert (in Sekundenbruchteilen) der Summe aus System- und Benutzer-CPU-Zeit des aktuellen Prozesses zurück. Die Zeit, die während eines Schlafens verstreicht, ist nicht eingeschlossen. Sie gilt per Definition für den gesamten Prozess. Der Bezugspunkt des zurückgegebenen Werts ist undefiniert, deshalb ist nur die Differenz zwischen den Ergebnissen zweier Aufrufe gültig.

Verwende process_time_ns(), um den Genauigkeitsverlust durch den Typ float zu vermeiden.

Added in version 3.3.

time.process_time_ns() → int

Wie process_time(), gibt die Zeit aber in Nanosekunden zurück.

Added in version 3.7.

time.sleep(seconds, /)

Setzt die Ausführung des aufrufenden Threads für die angegebene Anzahl Sekunden aus. Das Argument darf auch eine nicht ganze Zahl sein, um eine genauere Schlafdauer anzugeben.

Wird das Schlafen von einem Signal unterbrochen und löst der Signalhandler keine Ausnahme aus, beginnt das Schlafen mit neu berechneter Restzeit erneut.

Die Aussetzdauer kann um einen beliebigen Betrag länger sein als angefordert, weil im System andere Aktivitäten eingeplant werden.

Windows-Implementierung

Ist seconds unter Windows null, gibt der Thread den Rest seiner Zeitscheibe an jeden anderen lauffähigen Thread ab. Gibt es keine anderen lauffähigen Threads, kehrt die Funktion sofort zurück, und der Thread läuft weiter. Unter Windows 10 und neuer verwendet die Implementierung einen hochauflösenden Zeitgeber, der eine Auflösung von 100 Nanosekunden bietet. Ist seconds null, wird Sleep(0) verwendet.

Unix-Implementierung

• Verwendet clock_nanosleep(), sofern vorhanden (Auflösung: 1 Nanosekunde).

• Oder verwendet nanosleep(), sofern vorhanden (Auflösung: 1 Nanosekunde).

• Oder verwendet select() (Auflösung: 1 Mikrosekunde).

Bemerkung

Um einen Leerbefehl nachzubilden, verwende pass statt time.sleep(0).

Um die CPU freiwillig abzugeben, gib eine Ablaufplanungsstrategie für Echtzeit an und verwende stattdessen os.sched_yield().

Löst ein Auditing-Ereignis time.sleep mit dem Argument seconds aus.

Geändert in Version 3.5: Die Funktion schläft jetzt mindestens seconds, auch wenn das Schlafen von einem Signal unterbrochen wird, außer wenn der Signalhandler eine Ausnahme auslöst (die Begründung steht in PEP 475).

Geändert in Version 3.11: Unter Unix werden jetzt die Funktionen clock_nanosleep() und nanosleep() verwendet, sofern vorhanden. Unter Windows wird jetzt ein wartbarer Zeitgeber verwendet.

Geändert in Version 3.13: Löst ein Auditing-Ereignis aus.

Geändert in Version 3.15: Nimmt jede reelle Zahl an, nicht nur Ganz- oder Gleitkommazahlen.

time.strftime(format[, time_tuple])

Wandelt ein Tupel oder ein struct_time, das eine Zeit so darstellt, wie gmtime() oder localtime() sie zurückgeben, in eine Zeichenkette um, wie das Argument format sie angibt. Ist time_tuple nicht angegeben, wird die aktuelle Zeit verwendet, wie localtime() sie zurückgibt. format muss eine Zeichenkette sein. Liegt ein Feld in time_tuple außerhalb des zulässigen Bereichs, wird ValueError ausgelöst.

0 ist an jeder Stelle des Zeittupels ein zulässiges Argument. Ist der Wert dort normalerweise unzulässig, wird er auf einen richtigen Wert gezwungen.

Die folgenden Formatbezeichner können in die Zeichenkette format eingebettet werden. Sie sind hier ohne die wahlfreie Angabe von Feldbreite und Genauigkeit aufgeführt und werden im Ergebnis von strftime() durch die angegebenen Zeichen ersetzt:

Formatbezeichner	Bedeutung	Hinweise
%a	Abgekürzter Wochentagsname des Gebietsschemas.
%A	Vollständiger Wochentagsname des Gebietsschemas.
%b	Abgekürzter Monatsname des Gebietsschemas.
%B	Vollständiger Monatsname des Gebietsschemas.
%c	Passende Datums- und Zeitdarstellung des Gebietsschemas.
%d	Tag des Monats als Dezimalzahl [01,31].
%f	Mikrosekunden als Dezimalzahl [000000,999999].	(1)
%H	Stunde (24-Stunden-Zählung) als Dezimalzahl [00,23].
%I	Stunde (12-Stunden-Zählung) als Dezimalzahl [01,12].
%j	Tag des Jahres als Dezimalzahl [001,366].
%m	Monat als Dezimalzahl [01,12].
%M	Minute als Dezimalzahl [00,59].
%p	Entsprechung des Gebietsschemas für AM oder PM.	(2)
%S	Sekunde als Dezimalzahl [00,61].	(3)
%U	Wochennummer des Jahres (Sonntag als erster Tag der Woche) als Dezimalzahl [00,53]. Alle Tage eines neuen Jahres vor dem ersten Sonntag gelten als Woche 0.	(4)
%u	Tag der Woche (Montag ist 1, Sonntag ist 7) als Dezimalzahl [1, 7].
%w	Wochentag als Dezimalzahl [0(Sonntag),6].
%W	Wochennummer des Jahres (Montag als erster Tag der Woche) als Dezimalzahl [00,53]. Alle Tage eines neuen Jahres vor dem ersten Montag gelten als Woche 0.	(4)
%x	Passende Datumsdarstellung des Gebietsschemas.
%X	Passende Zeitdarstellung des Gebietsschemas.
%y	Jahr ohne Jahrhundert als Dezimalzahl [00,99].
%Y	Jahr mit Jahrhundert als Dezimalzahl.
%z	Zeitzonen-Offset, der eine positive oder negative Zeitdifferenz zu UTC/GMT in der Form +HHMM oder -HHMM angibt, wobei H dezimale Stundenstellen und M dezimale Minutenstellen darstellt [-23:59, +23:59]. [1]
%Z	Name der Zeitzone (keine Zeichen, wenn keine Zeitzone vorhanden ist). Veraltet. [1]
%G	ISO-8601-Jahr (ähnlich %Y, folgt aber den Regeln für das Kalenderjahr nach ISO 8601). Das Jahr beginnt mit der Woche, die den ersten Donnerstag des Kalenderjahres enthält.
%V	Wochennummer nach ISO 8601 (als Dezimalzahl [01,53]). Die erste Woche des Jahres ist die, die den ersten Donnerstag des Jahres enthält. Wochen beginnen am Montag.
%%	Ein wörtliches Zeichen '%'.

Hinweise:

1. Der Formatbezeichner %f gilt nur für strptime(), nicht für strftime(). Siehe aber auch datetime.datetime.strptime() und datetime.datetime.strftime(), wo der Formatbezeichner %f für Mikrosekunden gilt.

2. Zusammen mit der Funktion strptime() verwendet wirkt sich der Formatbezeichner %p nur dann auf das Stundenfeld der Ausgabe aus, wenn die Stunde mit dem Formatbezeichner %I zerlegt wird.

3. Der Bereich ist tatsächlich 0 bis 61. Der Wert 60 ist in Zeitstempeln gültig, die Schaltsekunden (leap seconds) darstellen, und der Wert 61 wird aus historischen Gründen unterstützt.

4. Zusammen mit der Funktion strptime() verwendet werden %U und %W nur dann in Berechnungen einbezogen, wenn der Wochentag und das Jahr angegeben sind.

Hier ein Beispiel, ein Format für Datumsangaben, das mit dem im Internet-E-Mail-Standard RFC 5322 angegebenen verträglich ist. [1]

>>> from time import gmtime, strftime
>>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
'Thu, 28 Jun 2001 14:17:15 +0000'

Auf bestimmten Plattformen können weitere Formatbezeichner unterstützt werden, aber nur die hier aufgeführten haben eine durch ANSI C standardisierte Bedeutung. Den vollständigen Satz der auf deiner Plattform unterstützten Formatbezeichner findest du in der Dokumentation zu strftime(3).

Auf einigen Plattformen darf eine wahlfreie Angabe von Feldbreite und Genauigkeit unmittelbar auf das einleitende '%' eines Formatbezeichners folgen, in der folgenden Reihenfolge. Auch das ist nicht portabel. Die Feldbreite ist normalerweise 2, außer bei %j, wo sie 3 ist.

time.strptime(string[, format])

Zerlegt eine Zeichenkette, die eine Zeit darstellt, nach einem Format. Der Rückgabewert ist ein struct_time, wie gmtime() oder localtime() es zurückgeben.

Der Parameter format verwendet dieselben Formatbezeichner wie strftime(). Voreingestellt ist "%a %b %d %H:%M:%S %Y", was der Formatierung entspricht, die ctime() zurückgibt. Lässt sich string nicht nach format zerlegen oder enthält es nach dem Zerlegen überzählige Daten, wird ValueError ausgelöst. Die Vorgabewerte, mit denen fehlende Daten aufgefüllt werden, wenn keine genaueren Werte abgeleitet werden können, sind (1900, 1, 1, 0, 0, 0, 0, 1, -1). Sowohl string als auch format müssen Zeichenketten sein.

Zum Beispiel:

>>> import time
>>> time.strptime("30 Nov 00", "%d %b %y")
time.struct_time(tm_year=2000, tm_mon=11, tm_mday=30, tm_hour=0, tm_min=0,
                 tm_sec=0, tm_wday=3, tm_yday=335, tm_isdst=-1)

Die Unterstützung für den Formatbezeichner %Z beruht auf den Werten in tzname und darauf, ob daylight wahr ist. Deshalb ist sie plattformspezifisch, außer beim Erkennen von UTC und GMT, die immer bekannt sind (und als Zeitzonen ohne Sommerzeit gelten).

Unterstützt werden nur die in der Dokumentation angegebenen Formatbezeichner. Weil strftime() je Plattform umgesetzt ist, kann es manchmal mehr Formatbezeichner anbieten als die hier aufgeführten. strptime() ist aber von jeder Plattform unabhängig und unterstützt deshalb nicht zwangsläufig alle verfügbaren Formatbezeichner, die nicht als unterstützt dokumentiert sind.

class time.struct_time

Der Typ der Zeitwertfolge, die gmtime(), localtime() und strptime() zurückgeben. Es ist ein Objekt mit der Schnittstelle eines benannten Tupels: Auf die Werte kann über den Index und über den Attributnamen zugegriffen werden. Die folgenden Werte sind vorhanden:

Index	Attribut	Werte
0	tm_year	(zum Beispiel 1993)
1	tm_mon	Bereich [1, 12]
2	tm_mday	Bereich [1, 31]
3	tm_hour	Bereich [0, 23]
4	tm_min	Bereich [0, 59]
5	tm_sec	Bereich [0, 61], siehe Hinweis (3) bei strftime()
6	tm_wday	Bereich [0, 6]; Montag ist 0
7	tm_yday	Bereich [1, 366]
8	tm_isdst	0, 1 oder -1 (siehe unten)
entfällt	tm_zone	Abkürzung des Zeitzonennamens
entfällt	tm_gmtoff	Offset östlich von UTC in Sekunden

Beachte, dass der Monatswert anders als in der C-Struktur im Bereich [1, 12] liegt, nicht [0, 11].

Bei Aufrufen von mktime() darf tm_isdst auf 1 gesetzt werden, wenn die Sommerzeit gilt, und auf 0, wenn sie nicht gilt. Der Wert -1 gibt an, dass das nicht bekannt ist, und führt üblicherweise dazu, dass der richtige Zustand eingesetzt wird.

Wird ein Tupel falscher Länge an eine Funktion übergeben, die ein struct_time erwartet, oder hat es Elemente falschen Typs, wird TypeError ausgelöst.

time.time() → float

Gibt die Zeit in Sekunden seit der Epoche (epoch) als Gleitkommazahl zurück. Wie Schaltsekunden (leap seconds) behandelt werden, hängt von der Plattform ab. Unter Windows und auf den meisten Unix-Systemen zählen die Schaltsekunden nicht zur Zeit in Sekunden seit der Epoche (epoch). Das wird üblicherweise Unix-Zeit genannt.

Beachte, dass die Zeit zwar immer als Gleitkommazahl zurückgegeben wird, aber nicht alle Systeme die Zeit mit einer besseren Genauigkeit als 1 Sekunde liefern. Diese Funktion gibt normalerweise nicht abnehmende Werte zurück, kann aber einen kleineren Wert als bei einem vorherigen Aufruf zurückgeben, wenn die Systemuhr zwischen den beiden Aufrufen zurückgestellt wurde.

Die Zahl, die time() zurückgibt, lässt sich in ein gebräuchlicheres Zeitformat (also Jahr, Monat, Tag, Stunde und so weiter) umwandeln: in UTC, indem du sie an die Funktion gmtime() übergibst, oder in Ortszeit, indem du sie an die Funktion localtime() übergibst. In beiden Fällen wird ein struct_time-Objekt zurückgegeben, über dessen Attribute auf die Bestandteile des Kalenderdatums zugegriffen werden kann.

Uhr:

• Unter Windows wird GetSystemTimePreciseAsFileTime() aufgerufen.

• Ruft clock_gettime(CLOCK_REALTIME) auf, sofern vorhanden.

• Andernfalls wird gettimeofday() aufgerufen.

Verwende time_ns(), um den Genauigkeitsverlust durch den Typ float zu vermeiden.

Geändert in Version 3.13: Ruft unter Windows GetSystemTimePreciseAsFileTime() statt GetSystemTimeAsFileTime() auf.

time.time_ns() → int

Wie time(), gibt die Zeit aber als ganze Zahl von Nanosekunden seit der Epoche (epoch) zurück.

Added in version 3.7.

time.thread_time() → float

Gibt den Wert (in Sekundenbruchteilen) der Summe aus System- und Benutzer-CPU-Zeit des aktuellen Threads zurück. Die Zeit, die während eines Schlafens verstreicht, ist nicht eingeschlossen. Sie gilt per Definition nur für diesen Thread. Der Bezugspunkt des zurückgegebenen Werts ist undefiniert, deshalb ist nur die Differenz zwischen den Ergebnissen zweier Aufrufe im selben Thread gültig.

Verwende thread_time_ns(), um den Genauigkeitsverlust durch den Typ float zu vermeiden.

Verfügbarkeit: Linux, Unix, Windows.

Unix-Systeme, die CLOCK_THREAD_CPUTIME_ID unterstützen.

Added in version 3.7.

time.thread_time_ns() → int

Wie thread_time(), gibt die Zeit aber in Nanosekunden zurück.

Added in version 3.7.

time.tzset()

Setzt die Regeln zur Zeitumrechnung zurück, die die Routinen der Bibliothek verwenden. Die Umgebungsvariable TZ gibt an, wie das geschieht. Sie setzt außerdem die Variablen tzname (aus der Umgebungsvariablen TZ), timezone (Sekunden westlich von UTC ohne Sommerzeit), altzone (Sekunden westlich von UTC mit Sommerzeit) und daylight (auf 0, wenn diese Zeitzone keine Sommerzeitregeln hat, oder auf einen Wert ungleich null, wenn es einen vergangenen, gegenwärtigen oder künftigen Zeitpunkt gibt, zu dem die Sommerzeit gilt).

Verfügbarkeit: Unix.

Bemerkung

Zwar kann das Ändern der Umgebungsvariablen TZ in vielen Fällen die Ausgabe von Funktionen wie localtime() beeinflussen, ohne dass tzset() aufgerufen wird, auf dieses Verhalten sollte man sich aber nicht verlassen.

Die Umgebungsvariable TZ sollte keine Leerzeichen enthalten.

Das Standardformat der Umgebungsvariablen TZ ist (zur Verdeutlichung mit Leerzeichen versehen):

std offset [dst [offset [,start[/time], end[/time]]]]

Die Bestandteile sind:

std und dst

Drei oder mehr alphanumerische Zeichen, die die Abkürzungen der Zeitzone angeben. Sie werden an time.tzname weitergegeben.

offset

Der Offset hat die Form ± hh[:mm[:ss]]. Er gibt den Wert an, der zur Ortszeit addiert wird, um UTC zu erhalten. Steht ein „-“ davor, liegt die Zeitzone östlich des Nullmeridians, andernfalls westlich. Folgt auf dst kein Offset, wird angenommen, dass die Sommerzeit der Normalzeit um eine Stunde vorausgeht.

start[/time], end[/time]

Gibt an, wann zur Sommerzeit und wann wieder zurück gewechselt wird. Die Start- und Enddaten haben eines der folgenden Formate:

Jn

Der julianische Tag n (1 <= n <= 365). Schalttage werden nicht mitgezählt, deshalb ist der 28. Februar in allen Jahren Tag 59 und der 1. März Tag 60.

n

Der nullbasierte julianische Tag (0 <= n <= 365). Schalttage werden mitgezählt, und der 29. Februar lässt sich angeben.

Mm.n.d

Der d-te Tag (0 <= d <= 6) der Woche n des Monats m des Jahres (1 <= n <= 5, 1 <= m <= 12, wobei Woche 5 „der letzte d-Tag im Monat m“ bedeutet, der in der vierten oder in der fünften Woche liegen kann). Woche 1 ist die erste Woche, in der der d-te Tag vorkommt. Tag null ist ein Sonntag.

time hat dasselbe Format wie offset, nur ist kein führendes Vorzeichen („-“ oder „+“) erlaubt. Ist time nicht angegeben, gilt 02:00:00.

>>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'02:07:36 05/08/03 EDT'
>>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'16:08:12 05/08/03 AEST'

Auf vielen Unix-Systemen (darunter *BSD, Linux, Solaris und Darwin) ist es bequemer, die Zeitzonenregeln über die Datenbank zoneinfo (tzfile(5)) des Systems anzugeben. Setze dazu die Umgebungsvariable TZ auf den Pfad der benötigten Zeitzonendatei, relativ zur Wurzel der zoneinfo-Zeitzonendatenbank des Systems, die üblicherweise unter /usr/share/zoneinfo liegt. Zum Beispiel 'US/Eastern', 'Australia/Melbourne', 'Egypt' oder 'Europe/Amsterdam'.

>>> os.environ['TZ'] = 'US/Eastern'
>>> time.tzset()
>>> time.tzname
('EST', 'EDT')
>>> os.environ['TZ'] = 'Egypt'
>>> time.tzset()
>>> time.tzname
('EET', 'EEST')

Konstanten für Uhrenkennungen

Diese Konstanten werden als Parameter für clock_getres() und clock_gettime() verwendet.

time.CLOCK_BOOTTIME

Identisch mit CLOCK_MONOTONIC, schließt aber auch jede Zeit ein, in der das System ausgesetzt ist.

Damit können Anwendungen eine monotone Uhr bekommen, die das Aussetzen berücksichtigt, ohne sich mit den Schwierigkeiten von CLOCK_REALTIME befassen zu müssen, die Sprünge aufweisen kann, wenn die Zeit über settimeofday() oder Ähnliches geändert wird.

Verfügbarkeit: Linux >= 2.6.39.

Added in version 3.7.

time.CLOCK_HIGHRES

Das Betriebssystem Solaris hat einen Zeitgeber CLOCK_HIGHRES, der eine möglichst gute Hardwarequelle zu verwenden versucht und nahezu Nanosekundenauflösung liefern kann. CLOCK_HIGHRES ist die nicht verstellbare, hochauflösende Uhr.

Verfügbarkeit: Solaris.

Added in version 3.3.

time.CLOCK_MONOTONIC

Uhr, die nicht gesetzt werden kann und die monotone Zeit seit einem nicht näher bestimmten Startpunkt darstellt.

Verfügbarkeit: Unix.

Added in version 3.3.

time.CLOCK_MONOTONIC_RAW

Ähnlich CLOCK_MONOTONIC, bietet aber Zugriff auf eine rohe, hardwaregestützte Zeit, die NTP-Anpassungen nicht unterliegt.

Verfügbarkeit: Linux >= 2.6.28, macOS >= 10.12.

Added in version 3.3.

time.CLOCK_MONOTONIC_RAW_APPROX

Ähnlich CLOCK_MONOTONIC_RAW, liest aber einen Wert, den das System beim Kontextwechsel zwischengespeichert hat, und ist deshalb weniger genau.

Verfügbarkeit: macOS >= 10.12.

Added in version 3.13.

time.CLOCK_PROCESS_CPUTIME_ID

Hochauflösender Zeitgeber je Prozess, von der CPU.

Verfügbarkeit: Unix.

Added in version 3.3.

time.CLOCK_PROF

Hochauflösender Zeitgeber je Prozess, von der CPU.

Verfügbarkeit: FreeBSD, NetBSD >= 7, OpenBSD.

Added in version 3.7.

time.CLOCK_TAI

Internationale Atomzeit

Das System muss eine aktuelle Schaltsekundentabelle haben, damit das die richtige Antwort liefert. PTP- oder NTP-Software kann eine Schaltsekundentabelle pflegen.

Verfügbarkeit: Linux.

Added in version 3.9.

time.CLOCK_THREAD_CPUTIME_ID

Threadspezifische CPU-Zeit-Uhr.

Verfügbarkeit: Unix.

Added in version 3.3.

time.CLOCK_UPTIME

Zeit, deren Absolutwert die Zeit ist, die das System gelaufen und nicht ausgesetzt war. Sie liefert eine genaue Messung der Laufzeit, sowohl absolut als auch als Intervall.

Verfügbarkeit: FreeBSD, OpenBSD >= 5.5.

Added in version 3.7.

time.CLOCK_UPTIME_RAW

Uhr, die monoton hochzählt und die Zeit seit einem beliebigen Punkt verfolgt, von Frequenz- oder Zeitanpassungen unbeeinflusst bleibt und nicht weiterzählt, während das System schläft.

Verfügbarkeit: macOS >= 10.12.

Added in version 3.8.

time.CLOCK_UPTIME_RAW_APPROX

Wie CLOCK_UPTIME_RAW, der Wert wird aber vom System bei Kontextwechseln zwischengespeichert und ist deshalb weniger genau.

Verfügbarkeit: macOS >= 10.12.

Added in version 3.13.

Die folgende Konstante ist der einzige Parameter, der an clock_settime() übergeben werden kann.

time.CLOCK_REALTIME

Echtzeituhr. Diese Uhr zu setzen erfordert entsprechende Rechte. Die Uhr ist für alle Prozesse dieselbe.

Verfügbarkeit: Unix.

Added in version 3.3.

Zeitzonenkonstanten

time.altzone

Der Offset der örtlichen Sommerzeitzone in Sekunden westlich von UTC, sofern eine festgelegt ist. Er ist negativ, wenn die örtliche Sommerzeitzone östlich von UTC liegt (wie in Westeuropa einschließlich Großbritannien). Verwende das nur, wenn daylight ungleich null ist. Siehe den Hinweis unten.

time.daylight

Ungleich null, wenn eine Sommerzeitzone festgelegt ist. Siehe den Hinweis unten.

time.timezone

Der Offset der örtlichen Zeitzone (ohne Sommerzeit) in Sekunden westlich von UTC (in den meisten Teilen Westeuropas negativ, in den USA positiv, in Großbritannien null). Siehe den Hinweis unten.

time.tzname

Ein Tupel aus zwei Zeichenketten: Die erste ist der Name der örtlichen Zeitzone ohne Sommerzeit, die zweite der Name der örtlichen Sommerzeitzone. Ist keine Sommerzeitzone festgelegt, sollte die zweite Zeichenkette nicht verwendet werden. Siehe den Hinweis unten.

Bemerkung

Bei den obigen Zeitzonenkonstanten (altzone, daylight, timezone und tzname) wird der Wert von den Zeitzonenregeln bestimmt, die beim Laden des Moduls oder beim letzten Aufruf von tzset() galten. Für Zeiten in der Vergangenheit kann er falsch sein. Es wird empfohlen, die Ergebnisse tm_gmtoff und tm_zone von localtime() zu verwenden, um Zeitzonenangaben zu bekommen.

Siehe auch

Modul datetime

Objektorientiertere Schnittstelle zu Datum und Zeit.

Modul locale

Dienste zur Internationalisierung. Die Einstellung des Gebietsschemas wirkt sich darauf aus, wie viele Formatbezeichner in strftime() und strptime() ausgelegt werden.

Modul calendar

Allgemeine Funktionen rund um den Kalender. timegm() ist die Umkehrung von gmtime() aus diesem Modul.

Fußnoten

[1] (1,2,3)

%Z zu verwenden ist inzwischen veraltet, aber die Escape-Folge %z, die zum bevorzugten Stunden-Minuten-Offset expandiert, wird nicht von allen ANSI-C-Bibliotheken unterstützt. Außerdem verlangt eine strenge Lesart des ursprünglichen Standards RFC 822 von 1982 eine zweistellige Jahreszahl (%y statt %Y), in der Praxis setzten sich vierstellige Jahreszahlen aber lange vor dem Jahr 2000 durch. Danach wurde RFC 822 überholt, und die vierstellige Jahreszahl wurde zunächst von RFC 1123 empfohlen und dann von RFC 2822 verbindlich gemacht, wobei RFC 5322 diese Anforderung fortführt.