"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" 現在
  在所有平台上都可用。

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

  +---------------------------+---------------------------+---------------------------+
  | 轉換來源                  | 轉換目標                  | 使用                      |
  |===========================|===========================|===========================|
  | 紀元秒數                  | 世界協調時間的            | "gmtime()"                |
  |                           | "struct_time"             |                           |
  +---------------------------+---------------------------+---------------------------+
  | 紀元秒數                  | 本地時間的 "struct_time"  | "localtime()"             |
  +---------------------------+---------------------------+---------------------------+
  | 世界協調時間的            | 紀元秒數                  | "calendar.timegm()"       |
  | "struct_time"             |                           |                           |
  +---------------------------+---------------------------+---------------------------+
  | 本地時間的 "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)

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

   * "'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()"。

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

   時鐘：

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

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

   如果睡眠被訊號中斷且訊號處理器未引發例外，則睡眠將以重新計算過的逾
   時 (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 版的變更: 引發一個稽核事件。

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"        | 一年中的週數（星期天作為一週的第一天），表示為十 | (4)     |
   |             | 進位數 [00,53]。新 的一年中，在第一個星期天之前  |         |
   |             | 的所有日子都被認定為第 0 週。                    |         |
   +-------------+--------------------------------------------------+---------+
   | "%u"        | 一週中的日期（周一為 1；週日為 7），表示為十進位 |         |
   |             | 數 [1,7]。                                       |         |
   +-------------+--------------------------------------------------+---------+
   | "%w"        | 週間日，表示為十進位數 [0（星期天）,6]。         |         |
   +-------------+--------------------------------------------------+---------+
   | "%W"        | 一年中的週數（星期一作為一週的第一天），表示為十 | (4)     |
   |             | 進位數 [00,53]。新 的一年中，在第一個星期一之前  |         |
   |             | 的所有日子都被認定為第 0 週。                    |         |
   +-------------+--------------------------------------------------+---------+
   | "%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]"
      表示何時切換至日光節約時間及何時切換回來。開始和結束日期的格式如
      以下其一：

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

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

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