# `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 is Coordinated Universal Time and superseded Greenwich Mean Time or GMT as the basis of international timekeeping. The acronym UTC is not a mistake but conforms to an earlier, language-agnostic naming scheme for time standards such as UT0, UT1, and 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)。

  Availability: Unix

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

  在 3.7 版被加入.

time.clock_getres(clk_id)

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

  Availability: Unix.

  在 3.3 版被加入.

time.clock_gettime(clk_id) → float

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

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

  Availability: Unix.

  在 3.3 版被加入.

time.clock_gettime_ns(clk_id) → int

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

  Availability: Unix.

  在 3.7 版被加入.

time.clock_settime(clk_id, time: float)

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

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

  Availability: Unix.

  在 3.3 版被加入.

time.clock_settime_ns(clk_id, time: int)

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

  Availability: Unix.

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

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

  - `'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 Constants。

  - 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`。

  如果時間戳超出 C 平台的 `localtime()` 或 `gmtime()` 函式支援的範圍，`localtime()` 可能會引發 `OverflowError`；在 `localtime()` 或 `gmtime()` 失敗時，會引發 `OSError`。通常會把年份限制在 1970 年到 2038 年之間。

time.mktime(t)

  這是 `localtime()` 的反函式。其引數是表示當地時間（不是 UTC）的 `struct_time` 或完整的 9 元組（因為需要 dst 旗標；如果 dst 為未知，則使用 `-1` 作為 dst 旗標）。它回傳一個浮點數，以與 `time()` 相容。如果輸入值不能表示為有效時間，將引發 `OverflowError` 或 `ValueError`（取決於無效值是被 Python 還是底層 C 函式庫捕獲）。它能生成時間的最早日期根據平台而有所不同。

time.monotonic() → float

  回傳單調時鐘（monotonic clock，即不能倒轉的時鐘）的值（以帶有小數的秒數表示）。該時鐘不受系統時鐘更新的影響。回傳值的參考點沒有定義，因此只有兩次呼叫結果之間的差異才是有效的。

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

  在 3.3 版被加入.

  在 3.5 版的變更: 此函式現在始終可用且涵蓋整個系統。

  在 3.10 版的變更: 在 macOS 上，此函式現在涵蓋整個系統。

time.monotonic_ns() → int

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

  在 3.7 版被加入.

time.perf_counter() → float

  回傳性能計數器的值（以帶有小數的秒數表示），即具有最高可用解析度來測量短時間間隔的時鐘。它包括睡眠時經過的時間，並且涵蓋整個系統。回傳值的參考點沒有定義，因此只有兩次呼叫結果之間的差異才是有效的。

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

  在 3.3 版被加入.

  在 3.10 版的變更: 在 Windows 上，此函式現在涵蓋整個系統。

time.perf_counter_ns() → int

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

  在 3.7 版被加入.

time.process_time() → float

  回傳當前行程的系統和用戶 CPU 時間之和（以帶有小數的秒數表示）。它不包括睡眠時經過的時間。根據定義，它涵蓋整個行程。回傳值的參考點沒有定義，因此只有兩次呼叫結果之間的差異才是有效的。

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

  在 3.3 版被加入.

time.process_time_ns() → int

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

  在 3.7 版被加入.

time.sleep(secs)

  在一個給定的秒數內暫停呼叫執行緒 (calling thread) 的執行。引數可以是浮點數，以表示更精確的睡眠時間。

  如果睡眠被訊號中斷且訊號處理器未引發例外，則睡眠將以重新計算過的逾時 (timeout) 重新開始。

  由於系統中其他活動的調度，暫停時間可能會比請求的時間長任意的量。

  Windows implementation

  On Windows, if secs is zero, the thread relinquishes the remainder of its time slice to any other thread that is ready to run. If there are no other threads ready to run, the function returns immediately, and the thread continues execution. On Windows 8.1 and newer the implementation uses a high-resolution timer which provides resolution of 100 nanoseconds. If secs is zero, `Sleep(0)` is used.

  Unix implementation

  - 如果可以，使用 `clock_nanosleep()`（解析度：1 奈秒）；

  - 或者使用 `nanosleep()`（解析度：1 奈秒）；

  - 或使用 `select()`（解析度：1 微秒）。

  備註

  To emulate a "no-op", use `pass` instead of `time.sleep(0)`.

  To voluntarily relinquish the CPU, specify a real-time scheduling policy and use `os.sched_yield()` instead.

  在 3.5 版的變更: 即使睡眠被訊號中斷，此函式現在至少還是會睡眠 secs，除非訊號處理器引發例外（理由請參閱 PEP 475）。

  在 3.11 版的變更: 在 Unix 上，如果可以的話現在會使用 `clock_nanosleep()` 和 `nanosleep()` 函式。在 Windows 上，現在使用可等待的計時器。

time.strftime(format[, t])

  將由 `gmtime()` 或 `localtime()` 回傳代表時間的一個元組或 `struct_time` 轉換為由 format 引數指定的字串。如果未提供 t，則使用由 `localtime()` 回傳的當前時間。format 必須是一個字串。如果 t 中的任何欄位超出允許範圍，將會引發 `ValueError`。

  0 在時間元組中的任何位置都是合法引數；如果元組中出現常見的錯誤，該值將被強制更改為正確的值。

  以下指令可以嵌入在 format 字串中。它們顯示時不帶可選的欄位寬度和精度規範，並在 `strftime()` 的結果中被標示的字元替換：

  指令 | 意義 | 註解
  --- | --- | ---
  `%a` | 區域設定的週間日 (weekday) 縮寫名稱。 |
  `%A` | 區域設定的完整週間日名稱。 |
  `%b` | 區域設定的縮寫月份名稱。 |
  `%B` | 區域設定的完整月份名稱。 |
  `%c` | 區域設定的合適的日期和時間的表示法。 |
  `%d` | 月份中的日期，表示為十進位數 [01,31]。 |

  `%f`

  微秒，表示為十進位數

    [000000,999999]。

  (1)

  `%H` | 小時（24 小時制），表示為十進位數 [00,23]。 |
  `%I` | 小時（12 小時制），表示為十進位數 [01,12]。 |
  `%j` | 一年中的第幾天，表示為十進位數 [001,366]。 |
  `%m` | 月份，表示為十進位數 [01,12]。 |
  `%M` | 分鐘，表示為十進位數 [00,59]。 |
  `%p` | 區域設定中相當於 AM 或 PM 的表示。 | (2)
  `%S` | 秒，表示為十進位數 [00,61]。 | (3)
  `%U` | 一年中的週數（星期天作為一週的第一天），表示為十進位數 [00,53]。新的一年中，在第一個星期天之前的所有日子都被認定為第 0 週。 | (4)
  `%u` | Day of the week (Monday is 1; Sunday is 7) as a decimal number [1, 7]. |
  `%w` | 週間日，表示為十進位數 [0（星期天）,6]。 |
  `%W` | 一年中的週數（星期一作為一週的第一天），表示為十進位數 [00,53]。新的一年中，在第一個星期一之前的所有日子都被認定為第 0 週。 | (4)
  `%x` | 區域設定的合適的日期表示法。 |
  `%X` | 區域設定的合適的時間表示法。 |
  `%y` | 去掉世紀的年份，表示為十進位數 [00,99]。 |
  `%Y` | 帶世紀的年份，表示為十進位數。 |
  `%z` | 時區偏移量，表示與 UTC/GMT 的正或負時間差，形式為 +HHMM 或 -HHMM，其中 H 代表十進位的小時數碼 (digits)，M 代表十進位的分鐘數碼 [-23:59, +23:59]。 [1] |
  `%Z` | 時區名稱（如果不存在時區，則無字元）。已被棄用。 [1] |
  `%G` | ISO 8601 year (similar to `%Y` but follows the rules for the ISO 8601 calendar year). The year starts with the week that contains the first Thursday of the calendar year. |
  `%V` | ISO 8601 week number (as a decimal number [01,53]). The first week of the year is the one that contains the first Thursday of the year. Weeks start on Monday. |
  `%%` | 字面意義上的 `'%'` 字元。 |

  註解：

  1. `%f` 格式的指令僅適用於 `strptime()`，不適用於 `strftime()`。然而，在 `datetime.datetime.strptime()` 和 `datetime.datetime.strftime()` 其中的 `%f` 格式的指令適用於微秒。

  2. 當與 `strptime()` 函式一起使用時，`%p` 指令僅在使用 `%I` 指令剖析小時時影響輸出小時的欄位。

  3. 範圍確實是從 `0` 到 `61`；數值 `60` 在表示 leap seconds 的時間戳中是有效的，而數值 `61` 是出於歷史因素而被支援。

  4. 當與 `strptime()` 函式一起使用時，`%U` 和 `%W` 僅在指定週間的某天和年份時用於計算中。

  以下是一個範例，其為一種與 RFC 2822 網際網路電子郵件標準中指定的日期格式兼容的格式。 [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) 文件。

  在某些平台上，可選的欄位寬度和精度規範可以以此順序緊跟在指令初始的 `'%'` 之後；這也是不可攜 (portable) 的。欄位寬度通常為 2，除了 `%j` 為 3。

time.strptime(string[, format])

  根據格式剖析表示時間的字串。回傳值是 `struct_time`，如同由 `gmtime()` 或 `localtime()` 回傳的一樣。

  format 參數使用與 `strftime()` 相同的指令；預設為 `"%a %b %d %H:%M:%S %Y"`，與 `ctime()` 回傳的格式匹配。如果 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` 是否為 true。因此，除了識別始終已知的 UTC 和 GMT（且被考慮為非日光節約時區）外，這是特定於平台的。

  僅支援文檔中指定的指令。由於 `strftime()` 是根據每個平台實作的，有時它可以提供比列出的還要更多的指令。但是 `strptime()` 與任何平台無關，因此不一定支援所有未記載為支援的指令。

class time.struct_time

  由 `gmtime()`、`localtime()` 和 `strptime()` 回傳的時間值序列的型別。它是一個具有 named tuple 介面的物件：值可以通過索引和屬性名稱存取。包含以下值：

  索引 | 屬性 | 值

  0

  tm_year

  （例如 1993）

  1

  tm_mon

  範圍 [1, 12]

  2

  tm_mday

  範圍 [1, 31]

  3

  tm_hour

  範圍 [0, 23]

  4

  tm_min

  範圍 [0, 59]

  5

  tm_sec

  範圍 [0, 61]；參見 `strftime()` 中的註釋 (2)

  6

  tm_wday

  範圍 [0, 6]；星期一是 0

  7

  tm_yday

  範圍 [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 起的時間（秒）至今的浮點數。對 leap seconds 的處理是與平台有關的。在 Windows 和大多數 Unix 系統上，閏秒不計入自 epoch 起的秒數中。這通常被稱為 Unix 時間。

  請注意，即使時間始終作為浮點數回傳，但並非所有系統都提供比 1 秒還更精確的時間。雖然此函式通常回傳非遞減的值，但如果在兩次呼叫之間系統時鐘被回調，則它可能回傳比之前呼叫更小的值。

  由 `time()` 回傳的數字可以通過傳遞給 `gmtime()` 函式轉換為 UTC 內更常見的時間格式（即年、月、日、小時等）或通過傳遞給 `localtime()` 函式轉換為當地時間。在這兩種情況下都會回傳一個 `struct_time` 物件，從中可以作為屬性存取日曆日期的組成部分。

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

time.time_ns() → int

  類似於 `time()`，但回傳自 epoch 起的以奈秒為單位的整數。

  在 3.7 版被加入.

time.thread_time() → float

  Return the value (in fractional seconds) of the sum of the system and user CPU time of the current thread. It does not include time elapsed during sleep. It is thread-specific by definition. The reference point of the returned value is undefined, so that only the difference between the results of two calls in the same thread is valid.

  Use `thread_time_ns()` to avoid the precision loss caused by the `float` type.

  Availability: Linux, Unix, Windows.

  Unix systems supporting `CLOCK_THREAD_CPUTIME_ID`.

  在 3.7 版被加入.

time.thread_time_ns() → int

  Similar to `thread_time()` but return time as nanoseconds.

  在 3.7 版被加入.

time.tzset()

  Reset the time conversion rules used by the library routines. The environment variable `TZ` specifies how this is done. It will also set the variables `tzname` (from the `TZ` environment variable), `timezone` (non-DST seconds West of UTC), `altzone` (DST seconds west of UTC) and `daylight` (to 0 if this timezone does not have any daylight saving time rules, or to nonzero if there is a time, past, present or future when daylight saving time applies).

  Availability: Unix.

  備註

  Although in many cases, changing the `TZ` environment variable may affect the output of functions like `localtime()` without calling `tzset()`, this behavior should not be relied on.

  The `TZ` environment variable should contain no whitespace.

  The standard format of the `TZ` environment variable is (whitespace added for clarity):

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

  Where the components are:

  `std` 和 `dst`

    Three or more alphanumerics giving the timezone abbreviations. These will be propagated into time.tzname

  `offset`

    The offset has the form: `± hh[:mm[:ss]]`. This indicates the value added the local time to arrive at UTC. If preceded by a '-', the timezone is east of the Prime Meridian; otherwise, it is west. If no offset follows dst, summer time is assumed to be one hour ahead of standard time.

  `start[/time], end[/time]`

    Indicates when to change to and back from DST. The format of the start and end dates are one of the following:

    `Jn`

      The Julian day n (1 <= n <= 365). Leap days are not counted, so in all years February 28 is day 59 and March 1 is day 60.

    `n`

      The zero-based Julian day (0 <= n <= 365). Leap days are counted, and it is possible to refer to February 29.

    `Mm.n.d`

      The d'th day (0 <= d <= 6) of week n of month m of the year (1 <= n <= 5, 1 <= m <= 12, where week 5 means "the last d day in month m" which may occur in either the fourth or the fifth week). Week 1 is the first week in which the d'th day occurs. Day zero is a Sunday.

    `time` has the same format as `offset` except that no leading sign ('-' or '+') is allowed. The default, if time is not given, is 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'

  On many Unix systems (including *BSD, Linux, Solaris, and Darwin), it is more convenient to use the system's zoneinfo (tzfile(5)) database to specify the timezone rules. To do this, set the `TZ` environment variable to the path of the required timezone datafile, relative to the root of the systems 'zoneinfo' timezone database, usually located at `/usr/share/zoneinfo`. For example, `'US/Eastern'`, `'Australia/Melbourne'`, `'Egypt'` or `'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 Constants

These constants are used as parameters for `clock_getres()` and `clock_gettime()`.

time.CLOCK_BOOTTIME

  Identical to `CLOCK_MONOTONIC`, except it also includes any time that the system is suspended.

  This allows applications to get a suspend-aware monotonic clock without having to deal with the complications of `CLOCK_REALTIME`, which may have discontinuities if the time is changed using `settimeofday()` or similar.

  Availability: Linux >= 2.6.39.

  在 3.7 版被加入.

time.CLOCK_HIGHRES

  The Solaris OS has a `CLOCK_HIGHRES` timer that attempts to use an optimal hardware source, and may give close to nanosecond resolution. `CLOCK_HIGHRES` is the nonadjustable, high-resolution clock.

  Availability: Solaris.

  在 3.3 版被加入.

time.CLOCK_MONOTONIC

  Clock that cannot be set and represents monotonic time since some unspecified starting point.

  Availability: Unix.

  在 3.3 版被加入.

time.CLOCK_MONOTONIC_RAW

  Similar to `CLOCK_MONOTONIC`, but provides access to a raw hardware-based time that is not subject to NTP adjustments.

  Availability: Linux >= 2.6.28, macOS >= 10.12.

  在 3.3 版被加入.

time.CLOCK_PROCESS_CPUTIME_ID

  High-resolution per-process timer from the CPU.

  Availability: Unix.

  在 3.3 版被加入.

time.CLOCK_PROF

  High-resolution per-process timer from the CPU.

  Availability: FreeBSD, NetBSD >= 7, OpenBSD.

  在 3.7 版被加入.

time.CLOCK_TAI

  International Atomic Time

  The system must have a current leap second table in order for this to give the correct answer. PTP or NTP software can maintain a leap second table.

  Availability: Linux.

  在 3.9 版被加入.

time.CLOCK_THREAD_CPUTIME_ID

  Thread-specific CPU-time clock.

  Availability: Unix.

  在 3.3 版被加入.

time.CLOCK_UPTIME

  Time whose absolute value is the time the system has been running and not suspended, providing accurate uptime measurement, both absolute and interval.

  Availability: FreeBSD, OpenBSD >= 5.5.

  在 3.7 版被加入.

time.CLOCK_UPTIME_RAW

  Clock that increments monotonically, tracking the time since an arbitrary point, unaffected by frequency or time adjustments and not incremented while the system is asleep.

  Availability: macOS >= 10.12.

  在 3.8 版被加入.

The following constant is the only parameter that can be sent to `clock_settime()`.

time.CLOCK_REALTIME

  System-wide real-time clock. Setting this clock requires appropriate privileges.

  Availability: Unix.

  在 3.3 版被加入.

## Timezone Constants

time.altzone

  The offset of the local DST timezone, in seconds west of UTC, if one is defined. This is negative if the local DST timezone is east of UTC (as in Western Europe, including the UK). Only use this if `daylight` is nonzero. See note below.

time.daylight

  Nonzero if a DST timezone is defined. See note below.

time.timezone

  The offset of the local (non-DST) timezone, in seconds west of UTC (negative in most of Western Europe, positive in the US, zero in the UK). See note below.

time.tzname

  A tuple of two strings: the first is the name of the local non-DST timezone, the second is the name of the local DST timezone. If no DST timezone is defined, the second string should not be used. See note below.

備註

For the above Timezone constants (`altzone`, `daylight`, `timezone`, and `tzname`), the value is determined by the timezone rules in effect at module load time or the last time `tzset()` is called and may be incorrect for times in the past. It is recommended to use the `tm_gmtoff` and `tm_zone` results from `localtime()` to obtain timezone information.

也參考

`datetime` 模組

  More object-oriented interface to dates and times.

`locale` 模組

  Internationalization services. The locale setting affects the interpretation of many format specifiers in `strftime()` and `strptime()`.

`calendar` 模組

  General calendar-related functions. `timegm()` is the inverse of `gmtime()` from this module.

註解

[1] (1,2,3)

The use of `%Z` is now deprecated, but the `%z` escape that expands to the preferred hour/minute offset is not supported by all ANSI C libraries. Also, a strict reading of the original 1982 RFC 822 standard calls for a two-digit year (`%y` rather than `%Y`), but practice moved to 4-digit years long before the year 2000. After that, RFC 822 became obsolete and the 4-digit year has been first recommended by RFC 1123 and then mandated by RFC 2822.