time --- 時間的訪問和轉換

---

該模塊提供了各種時間相關的函數。相關功能還可以參閱 datetime 和 calendar 模塊。

盡管此模塊始終可用，但并非所有平臺上都提供所有功能。 此模塊中定義的大多數函數是調用了所在平臺 C 語言庫的同名函數。 因為這些函數的語義因平臺而異,所以使用時最好查閱平臺相關文檔。

下面是一些術語和慣例的解釋.

• epoch 是時間開始的點，并且取決于平臺。對于Unix， epoch 是1970年1月1日00:00:00（UTC）。要找出給定平臺上的 epoch ，請查看 time.gmtime(0) 。

• 術語 Unix 紀元秒數 是指自國際標準時間 1970 年 1 月 1 日零時以來經過的總秒數，通常不包括 閏秒。 在所有符合 POSIX 標準的平臺上，閏秒都會從總秒數中被扣除。

• 此模塊中的功能可能無法處理紀元之前或將來的遠期日期和時間。未來的截止點由C庫決定；對于32位系統，它通常在2038年。

• 函數 strptime() 在接收到 %y 格式代碼時可以解析 2 位數的年份。 當解析 2 位數年份時，會按照 POSIX 和 ISO C 標準進行轉換：數值 69--99 映射為 1969--1999，而數值 0--68 被映射為 2000--2068。

• UTC是協調世界時（以前稱為格林威治標準時間，或GMT）。縮寫UTC不是錯誤，而是英語和法語之間的妥協。

• DST是夏令時，在一年中的一部分時間（通常）調整時區一小時。 DST規則很神奇（由當地法律確定），并且每年都會發生變化。 C 庫有一個包含本地規則的表（通常是從系統文件中讀取以獲得靈活性），并且在這方面是True Wisdom的唯一來源。

• 各種實時函數的精度可能低于表示其值或參數的單位所建議的精度。例如，在大多數Unix系統上，時鐘 "ticks" 僅為每秒50或100次。

• 另一方面， time() 和 sleep() 的精度優于它們的Unix等價物：時間表示為浮點數，time() 返回最準確的時間 （使用Unix gettimeofday() 如果可用），并且 sleep() 將接受非零分數的時間（Unix select() 用于實現此功能，如果可用）。

• 時間值由 gmtime()，localtime() 和 strptime() 返回，并被 asctime()， mktime() 和 strftime() 接受，是一個 9 個整數的序列。 gmtime()， localtime() 和 strptime() 的返回值還提供各個字段的屬性名稱。

  請參閱 struct_time 以獲取這些對象的描述。

  在 3.3 版更改: 在平臺支持相應的 struct tm 成員時，struct_time 類型被擴展提供 tm_gmtoff 和 tm_zone 屬性。

  在 3.6 版更改: struct_time 的屬性 tm_gmtoff 和 tm_zone 現在可在所有平臺上使用。

• 使用以下函數在時間表示之間進行轉換：

  從	到	使用
  seconds since the epoch	UTC 的 struct_time	gmtime()
  seconds since the epoch	本地時間的 struct_time	localtime()
  UTC 的 struct_time	seconds since the epoch	calendar.timegm()
  本地時間的 struct_time	seconds since the epoch	mktime()

函數

time.asctime([t])

轉換一個元組或 struct_time 表示的時間，由 gmtime() 或 localtime() 返回為以下形式的字符串： 'Sun Jun 20 23:21:05 1993' 。如果未提供 t ，則使用由 localtime() 返回的當前時間。 區域信息不被函數 asctime() 使用。

注解

與同名的C函數不同， asctime() 不添加尾隨換行符。

time.clock()

在Unix上，將當前處理器時間返回為以秒為單位的浮點數。精確度，實際上是“處理器時間”含義的定義，取決于同名C函數的精度。

在Windows上，此函數返回自第一次調用此函數以來經過的 wallclock 秒數，作為浮點數，基于Win32函數 QueryPerformanceCounter()。分辨率通常優于1微秒。

Deprecated since version 3.3, will be removed in version 3.8: 此函數的行為取決于平臺：根據你的需求，使用 perf_counter() 或 process_time() 獲得具有明確定義的行為。

time.pthread_getcpuclockid(thread_id)

返回指定的 thread_id 的特定于線程的CPU時間時鐘的 clk_id 。

使用 threading.Thread 對象的 threading.get_ident() 或 ident 屬性為 thread_id 獲取合適的值。

警告

傳遞無效的或過期的 thread_id 可能會導致未定義的行為，例如段錯誤。

可用性 ： Unix（有關詳細信息，請參見 pthread_getcpuclockid(3) 的手冊頁）。

3.7 新版功能.

time.clock_getres(clk_id)

返回指定時鐘 clk_id 的分辨率（精度）。有關 clk_id 的可接受值列表，請參閱 Clock ID 常量 。

可用性: Unix。

3.3 新版功能.

time.clock_gettime(clk_id) → float

返回指定 clk_id 時鐘的時間。有關 clk_id 的可接受值列表，請參閱 Clock ID 常量 。

可用性: Unix。

3.3 新版功能.

time.clock_gettime_ns(clk_id) → int

與 clock_gettime() 相似，但返回時間為納秒。

可用性: Unix。

3.7 新版功能.

time.clock_settime(clk_id, time: float)

設置指定 clk_id 時鐘的時間。 目前， CLOCK_REALTIME 是 clk_id 唯一可接受的值。

可用性: Unix。

3.3 新版功能.

time.clock_settime_ns(clk_id, time: int)

與 clock_settime() 相似，但設置時間為納秒。

可用性: Unix。

3.7 新版功能.

time.ctime([secs])

將以自 epoch 開始的秒數表示的時間轉換為表示本地時間的字符串。 如果未提供 secs 或為 None，則使用 time() 所返回的當前時間。 ctime(secs) 相當于 asctime(localtime(secs))。 區域信息不會被 ctime() 使用。

time.get_clock_info(name)

獲取有關指定時鐘的信息作為命名空間對象。 支持的時鐘名稱和讀取其值的相應函數是：

• 'clock': time.clock()

• 'monotonic': time.monotonic()

• 'perf_counter': time.perf_counter()

• 'process_time': time.process_time()

• 'thread_time': time.thread_time()

• 'time': time.time()

結果具有以下屬性：

• adjustable ： 如果時鐘可以自動更改（例如通過NTP守護程序）或由系統管理員手動更改，則為 True ，否則為 False 。

• implementation ： 用于獲取時鐘值的基礎C函數的名稱。有關可能的值，請參閱 Clock ID 常量 。

• monotonic ：如果時鐘不能倒退，則為 True ，否則為 False 。

• resolution ： 以秒為單位的時鐘分辨率（ float ）

3.3 新版功能.

time.gmtime([secs])

將以自 epoch 開始的秒數表示的時間轉換為 UTC 的 struct_time ，其中 dst 標志始終為零。 如果未提供 secs 或為 None ，則使用 time() 所返回的當前時間。 一秒以內的小數將被忽略。 有關 struct_time 對象的說明請參見上文。 有關此函數的逆操作請參閱 calendar.timegm()。

time.localtime([secs])

與 gmtime() 相似但轉換為當地時間。如果未提供 secs 或為 None ，則使用由 time() 返回的當前時間。當 DST 適用于給定時間時，dst標志設置為 1 。

time.mktime(t)

這是 localtime() 的反函數。它的參數是 struct_time 或者完整的 9 元組（因為需要 dst 標志；如果它是未知的則使用 -1 作為dst標志），它表示 local 的時間，而不是 UTC 。它返回一個浮點數，以便與 time() 兼容。如果輸入值不能表示為有效時間，則 OverflowError 或 ValueError 將被引發（這取決于Python或底層C庫是否捕獲到無效值）。它可以生成時間的最早日期取決于平臺。

time.monotonic() → float

返回單調時鐘的值（以小數秒為單位），即不能倒退的時鐘。時鐘不受系統時鐘更新的影響。返回值的參考點未定義，因此只有連續調用結果之間的差異才有效。

3.3 新版功能.

在 3.5 版更改: 該功能現在始終可用且始終在系統范圍內。

time.monotonic_ns() → int

與 monotonic() 相似，但是返回時間為納秒數。

3.7 新版功能.

time.perf_counter() → float

返回性能計數器的值（以小數秒為單位），即具有最高可用分辨率的時鐘，以測量短持續時間。它確實包括睡眠期間經過的時間，并且是系統范圍的。返回值的參考點未定義，因此只有連續調用結果之間的差異才有效。

3.3 新版功能.

time.perf_counter_ns() → int

與 perf_counter() 相似，但是返回時間為納秒。

3.7 新版功能.

time.process_time() → float

返回當前進程的系統和用戶CPU時間總和的值（以小數秒為單位）。它不包括睡眠期間經過的時間。根據定義，它在整個進程范圍中。返回值的參考點未定義，因此只有連續調用結果之間的差異才有效。

3.3 新版功能.

time.process_time_ns() → int

與 process_time() 相似，但是返回時間為納秒。

3.7 新版功能.

time.sleep(secs)

暫停執行調用線程達到給定的秒數。參數可以是浮點數，以指示更精確的睡眠時間。實際的暫停時間可能小于請求的時間，因為任何捕獲的信號將在執行該信號的捕獲例程后終止 sleep() 。此外，由于系統中其他活動的安排，暫停時間可能比請求的時間長任意量。

在 3.5 版更改: 即使睡眠被信號中斷，該函數現在至少睡眠 secs ，除非信號處理程序引發異常（參見 PEP 475 作為基本原理）。

time.strftime(format[, t])

轉換一個元組或 struct_time 表示的由 gmtime() 或 localtime() 返回的時間到由 format 參數指定的字符串。如果未提供 t ，則使用由 localtime() 返回的當前時間。 format 必須是一個字符串。如果 t 中的任何字段超出允許范圍，則引發 ValueError 。

0是時間元組中任何位置的合法參數；如果它通常是非法的，則該值被強制改為正確的值。

以下指令可以嵌入 format 字符串中。它們顯示時沒有可選的字段寬度和精度規范，并被 strftime() 結果中的指示字符替換：

指令	含義	注釋
%a	本地化的縮寫星期中每日的名稱。
%A	本地化的星期中每日的完整名稱。
%b	本地化的月縮寫名稱。
%B	本地化的月完整名稱。
%c	本地化的適當日期和時間表示。
%d	十進制數 [01,31] 表示的月中日。
%H	十進制數 [00,23] 表示的小時（24小時制）。
%I	十進制數 [01,12] 表示的小時（12小時制）。
%j	十進制數 [001,366] 表示的年中日。
%m	十進制數 [01,12] 表示的月。
%M	十進制數 [00,59] 表示的分鐘。
%p	本地化的 AM 或 PM 。	(1)
%S	十進制數 [00,61] 表示的秒。	(2)
%U	十進制數 [00,53] 表示的一年中的周數（星期日作為一周的第一天）。 在第一個星期日之前的新年中的所有日子都被認為是在第 0 周。	(3)
%w	十進制數 [0(星期日),6] 表示的周中日。
%W	十進制數 [00,53] 表示的一年中的周數（星期一作為一周的第一天）。 在第一個星期一之前的新年中的所有日子被認為是在第 0 周。	(3)
%x	本地化的適當日期表示。
%X	本地化的適當時間表示。
%y	十進制數 [00,99] 表示的沒有世紀的年份。
%Y	十進制數表示的帶世紀的年份。
%z	時區偏移以格式 +HHMM 或 -HHMM 形式的 UTC/GMT 的正或負時差指示，其中H表示十進制小時數字，M表示小數分鐘數字 [-23:59, +23:59] 。
%Z	時區名稱（如果不存在時區，則不包含字符）。
%%	字面的 '%' 字符。

注釋:

1. 當與 strptime() 函數一起使用時，如果使用 %I 指令來解析小時， %p 指令只影響輸出小時字段。

2. 范圍真的是 0 到 61 ；值 60 在表示 leap seconds 的時間戳中有效，并且由于歷史原因支持值 61 。

3. 當與 strptime() 函數一起使用時， %U 和 %W 僅用于指定星期幾和年份的計算。

下面是一個示例，一個與 RFC 2822 Internet電子郵件標準以兼容的日期格式。 1

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

某些平臺可能支持其他指令，但只有此處列出的指令具有 ANSI C 標準化的含義。要查看平臺支持的完整格式代碼集，請參閱 strftime(3) 文檔。

在某些平臺上，可選的字段寬度和精度規范可以按照以下順序緊跟在指令的初始 '%' 之后；這也不可移植。字段寬度通常為2，除了 %j ，它是3。

time.strptime(string[, format])

根據格式解析表示時間的字符串。 返回值為一個被 gmtime() 或 localtime() 返回的 struct_time 。

format 參數使用與 strftime() 相同的指令。 它默認為匹配 ctime() 所返回的格式 "%a %b %d %H:%M:%S %Y"` 。 如果 string 不能根據 format 來解析，或者解析后它有多余的數據，則會引發 ValueError。 當無法推斷出更準確的值時，用于填充任何缺失數據的默認值是 (1900, 1, 1, 0, 0, 0, 0, 1, -1) 。 string 和 format 都必須為字符串。

例如:

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

支持 %Z 指令是基于 tzname 中包含的值以及 daylight 是否為真。因此，它是特定于平臺的，除了識別始終已知的 UTC 和 GMT （并且被認為是非夏令時時區）。

僅支持文檔中指定的指令。因為每個平臺都實現了 strftime() ，它有時會提供比列出的指令更多的指令。但是 strptime() 獨立于任何平臺，因此不一定支持所有未記錄為支持的可用指令。

class time.struct_time

返回的時間值序列的類型為 gmtime() 、 localtime() 和 strptime() 。它是一個帶有 named tuple 接口的對象：可以通過索引和屬性名訪問值。 存在以下值：

索引	屬性	值
0	tm_year	（例如，1993）
1	tm_mon	range [1, 12]
2	tm_mday	range [1, 31]
3	tm_hour	range [0, 23]
4	tm_min	range [0, 59]
5	tm_sec	range [0, 61]； 見 strftime() 介紹中的 (2)
6	tm_wday	range [0, 6] ，周一為 0
7	tm_yday	range [1, 366]
8	tm_isdst	0, 1 或 -1；如下所示
N/A	tm_zone	時區名稱的縮寫
N/A	tm_gmtoff	以秒為單位的UTC以東偏離

請注意，與C結構不同，月份值是 [1,12] 的范圍，而不是 [0,11] 。

在調用 mktime() 時， tm_isdst 可以在夏令時生效時設置為1，而在夏令時不生效時設置為0。 值-1表示這是未知的，并且通常會導致填寫正確的狀態。

當一個長度不正確的元組被傳遞給期望 struct_time 的函數，或者具有錯誤類型的元素時，會引發 TypeError 。

time.time() → float

返回以浮點數表示的從 epoch 開始的秒數的時間值。 epoch 的具體日期和 leap seconds 的處理取決于平臺。 在 Windows 和大多數 Unix 系統中， epoch 是 1970 年 1 月 1 日 00:00:00 (UTC)，并且閏秒將不計入從 epoch 開始的秒數。 這通常被稱為 Unix 時間。 要了解給定平臺上 epoch 的具體定義，請查看 gmtime(0)。

請注意，即使時間總是作為浮點數返回，但并非所有系統都提供高于1秒的精度。雖然此函數通常返回非遞減值，但如果在兩次調用之間設置了系統時鐘，則它可以返回比先前調用更低的值。

返回的數字 time() 可以通過將其傳遞給 gmtime() 函數或轉換為UTC中更常見的時間格式（即年、月、日、小時等）或通過將它傳遞給 localtime() 函數獲得本地時間。在這兩種情況下都返回一個 struct_time 對象，日歷日期組件可以從中作為屬性訪問。

time.thread_time() → float

返回當前線程的系統和用戶CPU時間之和的值（以小數秒為單位）。它不包括睡眠期間經過的時間。根據定義，它是特定于線程的。返回值的參考點未定義，因此只有同一線程中連續調用結果之間的差異才有效。

可用性 ： Windows、 Linux、 Unix 系統支持 CLOCK_THREAD_CPUTIME_ID 。

3.7 新版功能.

time.thread_time_ns() → int

與 thread_time() 相似，但返回納秒時間。

3.7 新版功能.

time.time_ns() → int

與 time() 相似，但返回時間為用整數表示的自 epoch 以來所經過的納秒數。

3.7 新版功能.

time.tzset()

重置庫例程使用的時間轉換規則。環境變量 TZ 指定如何完成。它還將設置變量 tzname （來自 TZ 環境變量）， timezone （UTC的西部非DST秒）， altzone （UTC以西的DST秒）和 daylight （如果此時區沒有任何夏令時規則則為0，如果有夏令時適用的時間，無論過去、現在或未來，則為非零）。

可用性: Unix。

注解

雖然在很多情況下，更改 TZ 環境變量而不調用 tzset() 可能會影響函數的輸出，例如 localtime() ，不應該依賴此行為。

TZ 不應該包含空格。

TZ 環境變量的標準格式是（為了清晰起見，添加了空格）:

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

組件的位置是：

std 和 dst

三個或更多字母數字，給出時區縮寫。這些將傳到 time.tzname

offset

偏移量的形式為： ± hh[:mm[:ss]] 。這表示添加到達UTC的本地時間的值。如果前面有 '-' ，則時區位于本初子午線的東邊；否則，在它是西邊。如果dst之后沒有偏移，則假設夏令時比標準時間提前一小時。

start[/time], end[/time]

指示何時更改為DST和從DST返回。開始日期和結束日期的格式為以下之一：

Jn

Julian日 n （1 <= n <= 365）。閏日不計算在內，因此在所有年份中，2月28日是第59天，3月1日是第60天。

n

從零開始的Julian日（0 <= n <= 365）。 閏日計入，可以引用2月29日。

Mm.n.d

一年中 m 月的第 n 周（1 <= n <= 5 ，1 <= m <= 12 ，第 5 周表示 “可能在 m 月第 4 周或第 5 周出現的最后第 d 日”）的第 d 天（0 <= d <= 6）。 第 1 周是第 d 天發生的第一周。 第 0 天是星期天。

time 的格式與 offset 的格式相同，但不允許使用前導符號（ '-' 或 '+' ）。如果沒有給出時間，則默認值為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'

在許多Unix系統（包括 *BSD ， Linux ， Solaris 和 Darwin 上），使用系統的區域信息（ tzfile(5) ）數據庫來指定時區規則會更方便。為此，將 TZ 環境變量設置為所需時區數據文件的路徑，相對于系統 'zoneinfo' 時區數據庫的根目錄，通常位于 /usr/share/zoneinfo 。 例如，'US/Eastern' 、 'Australia/Melbourne' 、 'Egypt' 或 'Europe/Amsterdam'。

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

Clock ID 常量

這些常量用作 clock_getres() 和 clock_gettime() 的參數。

time.CLOCK_BOOTTIME

與 CLOCK_MONOTONIC 相同，除了它還包括系統暫停的任何時間。

這允許應用程序獲得一個暫停感知的單調時鐘，而不必處理 CLOCK_REALTIME 的復雜性，如果使用 settimeofday() 或類似的時間更改時間可能會有不連續性。

可用性: Linux 2.6.39 或更新

3.7 新版功能.

time.CLOCK_HIGHRES

Solaris OS 有一個 CLOCK_HIGHRES 計時器，試圖使用最佳硬件源，并可能提供接近納秒的分辨率。 CLOCK_HIGHRES 是不可調節的高分辨率時鐘。

可用性: Solaris.

3.3 新版功能.

time.CLOCK_MONOTONIC

無法設置的時鐘，表示自某些未指定的起點以來的單調時間。

可用性: Unix。

3.3 新版功能.

time.CLOCK_MONOTONIC_RAW

類似于 CLOCK_MONOTONIC ，但可以訪問不受NTP調整影響的原始硬件時間。

可用性: Linux 2.6.28 和更新版本， macOS 10.12 和更新版本。

3.3 新版功能.

time.CLOCK_PROCESS_CPUTIME_ID

來自CPU的高分辨率每進程計時器。

可用性: Unix。

3.3 新版功能.

time.CLOCK_PROF

來自CPU的高分辨率每進程計時器。

可用性: FreeBSD， NetBSD 7 或更新， OpenBSD.

3.7 新版功能.

time.CLOCK_THREAD_CPUTIME_ID

特定于線程的CPU時鐘。

可用性: Unix。

3.3 新版功能.

time.CLOCK_UPTIME

該時間的絕對值是系統運行且未暫停的時間，提供準確的正常運行時間測量，包括絕對值和間隔值。

可用性: FreeBSD， OpenBSD 5.5 或更新。

3.7 新版功能.

以下常量是唯一可以發送到 clock_settime() 的參數。

time.CLOCK_REALTIME

系統范圍的實時時鐘。 設置此時鐘需要適當的權限。

可用性: Unix。

3.3 新版功能.

時區常量

time.altzone

本地DST時區的偏移量，以UTC為單位的秒數，如果已定義。如果當地DST時區在UTC以東（如在西歐，包括英國），則是負數。 只有當 daylight 非零時才使用它。 見下面的注釋。

time.daylight

如果定義了DST時區，則為非零。 見下面的注釋。

time.timezone

本地（非DST）時區的偏移量，UTC以西的秒數（西歐大部分地區為負，美國為正，英國為零）。 見下面的注釋。

time.tzname

兩個字符串的元組：第一個是本地非DST時區的名稱，第二個是本地DST時區的名稱。 如果未定義DST時區，則不應使用第二個字符串。 見下面的注釋。

注解

對于上述時區常量（ altzone 、 daylight 、 timezone 和 tzname ），該值由模塊加載時有效的時區規則確定，或者最后一次 tzset() 被調用時，并且在過去的時間可能不正確。建議使用來自 localtime() 結果的 tm_gmtoff 和 tm_zone 來獲取時區信息。

參見

模塊 datetime

更多面向對象的日期和時間接口。

模塊 locale

國際化服務。 區域設置會影響 strftime() 和 strptime() 中許多格式說明符的解析。

模塊 calendar

一般日歷相關功能。這個模塊的 timegm() 是函數 gmtime() 的反函數。

備注

1

現在不推薦使用 %Z ，但是所有 ANSI C 庫都不支持擴展為首選小時/分鐘偏移量的``%z``轉義符。 此外，嚴格的 1982 年原始 RFC 822 標準要求兩位數的年份（%y而不是%Y），但是實際在2000年之前很久就轉移到了4位數年。之后， RFC 822 已經廢棄了，4位數的年份首先被推薦 RFC 1123 ，然后被 RFC 2822 強制執行。