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

   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"        | 一年中的週數（星期天作為一週的第一天），表示為十 | (4)     |
   |             | 進位數 [00,53]。新 的一年中，在第一個星期天之前  |         |
   |             | 的所有日子都被認定為第 0 週。                    |         |
   +-------------+--------------------------------------------------+---------+
   | "%u"        | Day of the week (Monday is 1; Sunday is 7) as a  |         |
   |             | decimal number [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 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:

      "J*n*"
         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.

      "M*m*.*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] 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**.
