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

  可用性: 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)

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

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

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

  在 3.3 版被加入.

  在 3.15 版的變更: Accepts any real number as time, not only integer or float.

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()` 不使用區域資訊。

  在 3.15 版的變更: Accepts any real number, not only integer or float.

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: 如果時鐘可以設定為向前或向後跳轉時間則為 `True`，否則為 `False`。不指漸進式的 NTP 速率調整。

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

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

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

  在 3.3 版被加入.

time.gmtime([secs])

  將自 epoch 起以秒表示的時間轉換為 UTC 中的 `struct_time`，其中 dst 旗標始終為零。如果未提供 secs 或其為 `None`，則使用由 `time()` 回傳的目前時間。忽略秒的分數部分。關於 `struct_time` 物件的描述，請參閱上文。此函式的反運算請參閱 `calendar.timegm()`。

  在 3.15 版的變更: Accepts any real number, not only integer or float.

time.localtime([secs])

  類似於 `gmtime()`，但轉換為當地時間。如果未提供 secs 或其為 `None`，則使用由 `time()` 回傳的目前時間。當 DST 適用於給定時間時，dst 旗標會被設定為 `1`。

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

  在 3.15 版的變更: Accepts any real number, not only integer or float.

time.mktime(t)

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

time.monotonic() → float

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

  時鐘：

  - 在 Windows 上，呼叫 `QueryPerformanceCounter()` 和 `QueryPerformanceFrequency()`。

  - 在 macOS 上，呼叫 `mach_absolute_time()` 和 `mach_timebase_info()`。

  - 在 HP-UX 上，呼叫 `gethrtime()`。

  - 如果可以的話，呼叫 `clock_gettime(CLOCK_HIGHRES)`。

  - 否則，呼叫 `clock_gettime(CLOCK_MONOTONIC)`。

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

  在 3.3 版被加入.

  在 3.5 版的變更: 此函式現在始終可用且時鐘對於所有行程都會是相同。

  在 3.10 版的變更: 在 macOS 上，時鐘對於所有行程都會是相同。

time.monotonic_ns() → int

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

  在 3.7 版被加入.

time.perf_counter() → float

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

  在 CPython 上，使用與 `time.monotonic()` 相同的時鐘，且其為單調時鐘（即不能倒轉的時鐘）。

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

  在 3.3 版被加入.

  在 3.10 版的變更: 在 Windows 上，時鐘對於所有行程都會是相同。

  在 3.13 版的變更: 使用與 `time.monotonic()` 相同的時鐘。

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)

  Suspend execution of the calling thread for the given number of seconds. The argument may be a non-integer to indicate a more precise sleep time.

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

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

  Windows 實作

  在 Windows 上，如果 secs 為零，則執行緒將其剩餘的時間片段讓給任何準備運行的其他執行緒。如果沒有其他執行緒準備運行，該函式將立即回傳，而執行緒會繼續執行。在 Windows 10 及更新的版本中，此實作使用高解析度計時器，其解析度為 100 奈秒。如果 secs 為零，則使用 `Sleep(0)`。

  Unix 實作

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

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

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

  備註

  要模擬「無動作 (no-op)」，請使用 `pass` 而不是 `time.sleep(0)`。

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

  引發一個帶有引數 `secs` 的稽核事件 (auditing event) `time.sleep`。

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

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

  在 3.13 版的變更: 引發一個稽核事件。

  在 3.15 版的變更: Accepts any real number, not only integer or float.

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` | 一週中的日期（周一為 1；週日為 7），表示為十進位數 [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 年（類似於 `%Y`，但遵循 ISO 8601 日曆年的規則）。年份從包含該日曆年第一個星期四的那一週開始。 |
  `%V` | ISO 8601 週數（以十進位數表示 [01,53]）。年份的第一週是包含該年第一個星期四的那一週。每週從星期一開始。 |
  `%%` | 字面意義上的 `'%'` 字元。 |

  註解：

  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 5322 網際網路電子郵件標準中指定的日期格式兼容的格式。 [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` 物件，從中可以作為屬性存取日曆日期的組成部分。

  時鐘：

  - 在 Windows 上，呼叫 `GetSystemTimePreciseAsFileTime()`。

  - 如果可以的話，呼叫 `clock_gettime(CLOCK_REALTIME)`。

  - 否則，呼叫 `gettimeofday()`。

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

在 3.13 版的變更: 在 Windows 上，呼叫 `GetSystemTimePreciseAsFileTime()` 而不是 `GetSystemTimeAsFileTime()`。

time.time_ns() → int

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

  在 3.7 版被加入.

time.thread_time() → float

  回傳目前執行緒的系統和用戶 CPU 時間之和（以帶有小數的秒數表示）。它不包括睡眠期間經過的時間。根據定義，這是執行緒特定 (thread-specific) 的。回傳值的參照點未定義，因此只有同一執行緒中兩次呼叫結果之間的差異才是有效的。

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

  可用性: Linux, Unix, Windows.

  有支援 `CLOCK_THREAD_CPUTIME_ID` 的 Unix 系統。

  在 3.7 版被加入.

time.thread_time_ns() → int

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

  在 3.7 版被加入.

time.tzset()

  重置函式庫常式 (routine) 使用的時間轉換規則。環境變數 `TZ` 指定了這一過程的實施方式。它還會設定變數 `tzname`（來自 `TZ` 環境變數）、`timezone`（非日光節約時間的 UTC 以西的時間偏移，單位為秒）、`altzone`（日光節約時間的 UTC 以西的時間偏移，單位為秒）和 `daylight`（如果該時區沒有日光節約時間規則，則設定為 0；如果在過去、現在或未來的某個時間有日光節約時間規則，則設置為非零的值）。

  可用性: Unix.

  備註

  雖然在許多情況下，更改 `TZ` 環境變數可能會在沒有呼叫 `tzset()` 的情況下影響 `localtime()` 等函式的輸出，但是這種行為是不該被依賴的。

  `TZ` 環境變數不應包含空格字元。

  `TZ` 環境變數的標準格式為（為了清楚表達，中間增加了空格字元）：

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

  其中各個組成部分為：

  `std` 和 `dst`

    三個或更多字母與數字 (alphanumerics) 組成的時區縮寫。這些縮寫會被傳播到 time.tzname 中。

  `offset`

    偏移量的格式為：`± hh[:mm[:ss]]`。這表示為達到 UTC 而增加到當地時間的值。如果以 '-' 開頭，則表示該時區位於本初子午線以東；否則，位於其西。如果 dst 之後沒有偏移量，則假定日光時間比標準時間快一小時。

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

    表示何時切換至日光節約時間及何時切換回來。開始和結束日期的格式如以下其一：

    `Jn`

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

    `n`

      從 0 開始的儒略日 (0 <= n <= 365)。閏日會計算，因此可以適用至 2 月 29 日。

    `Mm.n.d`

      一年中第 m 月的第 n 週的第 d 天（0 <= d <= 6，1 <= n <= 5，1 <= m <= 12，其中 n 為 5 表示「該月的最後一個第 d 天」，這可能出現在第四或第五週）。第 1 週是 d 天首次出現的那一週。第零天為星期天。

    `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）上，使用系統的 zoneinfo (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')

## 時鐘 ID 常數

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

time.CLOCK_BOOTTIME

  與 `CLOCK_MONOTONIC` 基本相同，不同之處在於它還包括系統暫停的任何時間。

  這允許應用程式取得一個能夠感知暫停的單調時鐘，而無需處理 `CLOCK_REALTIME` 的複雜情況，後者在使用 `settimeofday()` 或類似函式更改時間時可能會出現不連續的情況。

  可用性: Linux >= 2.6.39.

  在 3.7 版被加入.

time.CLOCK_HIGHRES

  Solaris 作業系統具有 `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_MONOTONIC_RAW_APPROX

  類似於 `CLOCK_MONOTONIC_RAW`，但讀取的是系統在情境切換時快取的值，因此精準度較低。

  可用性: macOS >= 10.12.

  在 3.13 版被加入.

time.CLOCK_PROCESS_CPUTIME_ID

  來自 CPU 的高解析度每個行程的計時器。

  可用性: Unix.

  在 3.3 版被加入.

time.CLOCK_PROF

  來自 CPU 的高解析度每個行程的計時器。

  可用性: FreeBSD, NetBSD >= 7, OpenBSD.

  在 3.7 版被加入.

time.CLOCK_TAI

  國際原子時間

  系統必須擁有目前的閏秒表才能給出正確答案。PTP 或 NTP 軟體可以維護閏秒表。

  可用性: Linux.

  在 3.9 版被加入.

time.CLOCK_THREAD_CPUTIME_ID

  執行緒相關的 CPU 時間時鐘。

  可用性: Unix.

  在 3.3 版被加入.

time.CLOCK_UPTIME

  表示系統運作且無暫停的絕對時間，提供包括絕對時間 (absolute) 和時間區間 (interval) 的精確的正常上線時間 (uptime) 測量。

  可用性: FreeBSD, OpenBSD >= 5.5.

  在 3.7 版被加入.

time.CLOCK_UPTIME_RAW

  單調增量的時鐘，從某個任意點開始計時，不受頻率或時間調整影響，並且在系統休眠時不增量。

  可用性: macOS >= 10.12.

  在 3.8 版被加入.

time.CLOCK_UPTIME_RAW_APPROX

  類似於 `CLOCK_UPTIME_RAW`，但該值在情境切換時由系統快取，因此精準度較低。

  可用性: macOS >= 10.12.

  在 3.13 版被加入.

以下常數是唯一可以傳遞給 `clock_settime()` 的參數。

time.CLOCK_REALTIME

  即時時鐘。設定此時鐘需要適當的權限。時鐘對於所有行程都會是相同。

  可用性: Unix.

  在 3.3 版被加入.

## 時區常數

time.altzone

  如果本地 DST 時區有被定義，則此值為本地 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()` 中許多格式指定符號 (format specifiers) 的解譯。

`calendar` 模組

  通用的日曆相關函式。`timegm()` 是本模組中 `gmtime()` 的反函式。

註腳

[1] (1,2,3)

現在 `%Z` 已被棄用，`%z` 藉由擴展為偏好的小時/分鐘偏移而逃離了被棄用的命運，但其並不是被所有 ANSI C 函式庫支援。此外，嚴格按照 1982 年的 RFC 822 標準，應該使用兩位數年份（`%y` 而不是 `%Y`），但實作中在 2000 年之前就已經轉向使用四位數年份。之後，RFC 822 被淘汰，四位數年份首先由 RFC 1123 推薦，然後由 RFC 2822 正式批准，並以 RFC 5322 繼續此需求。