time --- 時間存取與轉換

這個模組提供了各種與時間相關的函式。若要查看相關功能，請參閱 datetime 和 calendar 模組。

雖然這個模組隨時可用，但並非所有函式在所有平台上都可用。這個模組中定義的大多數函式都會呼叫 C 語言平台的函式庫中具有相同名稱的函式。由於這些函式的語義因平台而異，所以偶爾查閱平台文件可能會有所幫助。

以下是對一些術語和慣例的說明。

  • epoch 是起始的時間點，即 time.gmtime(0) 的回傳值。在所有平台上，它是 1970 年 1 月 1 日，00:00:00（UTC）。

  • 術語 seconds since the epoch（紀元秒數） 是指從 epoch（紀元）開始經過的總秒數，通常不包括 leap seconds。在所有符合 POSIX 標準的平台上，leap seconds （閏秒）都不計入這個總數。

  • 這個模組中的函式可能無法處理 epoch 之前或遙遠未來的日期和時間。未來的臨界點由 C 函式庫決定；對於 32 位元系統來說通常是在 2038 年。

  • 函式 strptime() 在給定 %y 格式碼時可以剖析 (parse) 兩位數的年份。當剖析兩位數的年份時，它們會根據 POSIX 和 ISO C 標準進行轉換：69--99 的值對映到 1969--1999，0--68 的值對映到 2000--2068。

  • UTC 是 Coordinated Universal Time（世界協調時間），取代了 Greenwich Mean Time（格林威治標準時間）或 GMT 成為國際計時的基礎。UTC 這個縮寫並非錯誤，而是沿用了更早期、與語言無關的時間標準命名方式，如 UT0、UT1 和 UT2。

  • DST 是 Daylight Saving Time（日光節約時間），一年中的某些時段（通常）將會時區調整一小時。DST 的規則是根據當地法律決定的，且可能每年不同。C 函式庫有一個包含當地規則的表（通常會為了靈活性而從系統文件中讀取），在這方面是唯一的真正依據。

  • 各種即時 (real-time) 函式的精確度可能低於其值或引數所表示的單位所建議的精確度。例如，在大多數 Unix 系統上，時鐘每秒只「跳」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 現在在所有平台上都可用。

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

    轉換來源

    轉換目標

    使用

    紀元秒數

    世界協調時間的 struct_time

    gmtime()

    紀元秒數

    本地時間的 struct_time

    localtime()

    世界協調時間的 struct_time

    紀元秒數

    calendar.timegm()

    本地時間的 struct_time

    紀元秒數

    mktime()

函式

time.asctime([t])

將由 gmtime() 或 localtime() 回傳的元組或 struct_time 表示的時間轉換為以下格式的字串：'Sun Jun 20 23:21:05 1993'。日期欄位為兩個字元長，如果日期是個位數，則用空格填充，例如：'Wed Jun  9 04:26:40 1993'。

如果沒有提供 t，則使用由 localtime() 回傳的目前時間。asctime() 不使用區域資訊。

備註

與同名的 C 函式不同，asctime() 不會添加結尾的換行字元。

time.pthread_getcpuclockid(thread_id)

為指定的 thread_id 回傳執行緒專用 CPU-time 時鐘的 clk_id。

使用 threading.get_ident() 或 threading.Thread 物件的 ident 屬性來取得適用於 thread_id 的值。

警告

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

可用性: Unix

若需更多資訊，請參閱 pthread_getcpuclockid(3) 的說明文件。

在 3.7 版被加入.

time.clock_getres(clk_id)

回傳指定時鐘 clk_id 的解析度（精確度）。有關 clk_id 可接受的值的串列，請參閱 時鐘 ID 常數。

可用性: Unix.

在 3.3 版被加入.

time.clock_gettime(clk_id) → float

回傳指定時鐘 clk_id 的時間。有關 clk_id 可接受的值的串列，請參閱 時鐘 ID 常數。

使用 clock_gettime_ns() 以避免 float 型別造成的精確度損失。

可用性: Unix.

在 3.3 版被加入.

time.clock_gettime_ns(clk_id) → int

類似於 clock_gettime()，但回傳以奈秒 (nanoseconds) 為單位的時間。

可用性: Unix.

在 3.7 版被加入.

time.clock_settime(clk_id, time: float)

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

使用 clock_settime_ns() 以避免 float 型別造成的精確度損失。

可用性: Unix, not Android, not iOS.

在 3.3 版被加入.

time.clock_settime_ns(clk_id, time: int)

類似於 clock_settime()，但設定以奈秒為單位的時間。

可用性: Unix, not Android, not iOS.

在 3.7 版被加入.

time.ctime([secs])

將自 epoch 起以秒表示的時間轉換為表示當地時間且符合以下格式的字串：'Sun Jun 20 23:21:05 1993'。日期欄位為兩個字元長，如果日期是個位數，則用空格填充，例如：'Wed Jun  9 04:26:40 1993'。

如果未提供 secs 或其為 None，則使用由 time() 回傳的目前時間。ctime(secs) 等同於 asctime(localtime(secs))。ctime() 不使用區域資訊。

time.get_clock_info(name)

取得指定時鐘的資訊作為命名空間物件。支援的時鐘名稱及讀取他們的值的對應函式如下：

其結果具有以下屬性：

  • adjustable: 如果時鐘可以設定為向前或向後跳轉時間則為 True，否則為 False。不指漸進式的 NTP 速率調整。

  • implementation: 用於取得時鐘的值的底層 C 函式名稱。有關可能的值，請參閱 時鐘 ID 常數。

  • monotonic: 如果時鐘不能倒轉，則為 True，否則為 False

  • resolution: 以秒 (float) 為單位的時鐘的解析度

在 3.3 版被加入.

time.gmtime([secs])

將自 epoch 起以秒表示的時間轉換為 UTC 中的 struct_time，其中 dst 旗標始終為零。如果未提供 secs 或其為