time --- 時間的訪問和轉換?

函數?

time.asctime([t])?

轉換由 gmtime() 或 localtime() 所返回的表示時間的元組或 struct_time 為以下形式的字符串: 'Sun Jun 20 23:21:05 1993'。 日期字段的長度為兩個字符，如果日期只有一個數字則會以零填充，例如: 'Wed Jun  9 04:26:40 1993'。

如果未提供 t，則會使用 localtime() 所返回的當前時間。 asctime() 不會使用區(qū)域設置信息。

備注

與同名的C函數不同， asctime() 不添加尾隨換行符。

time.pthread_getcpuclockid(thread_id)?

返回指定的 thread_id 的特定于線程的CPU時間時鐘的 clk_id 。

使用 threading.Thread 對象的 threading.get_ident() 或 ident 屬性為 thread_id 獲取合適的值。

警告

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

可用性 ： Unix（有關詳細信息，請參見 pthread_getcpuclockid(3) 的手冊頁）。

3.7 新版功能.

time.clock_getres(clk_id)?

返回指定時鐘 clk_id 的分辨率（精度）。有關 clk_id 的可接受值列表，請參閱 Clock ID 常量 。

可用性: Unix。

3.3 新版功能.

time.clock_gettime(clk_id) → float?

返回指定 clk_id 時鐘的時間。有關 clk_id 的可接受值列表，請參閱 Clock ID 常量 。

使用 clock_gettime_ns() 以避免 float 類型導致的精度損失。

可用性: Unix。

3.3 新版功能.

time.clock_gettime_ns(clk_id) → int?

與 clock_gettime() 相似，但返回時間為納秒。

可用性: Unix。

3.7 新版功能.

time.clock_settime(clk_id, time: float)?

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

使用 clock_settime_ns() 以避免 float 類型導致的精度損失。

可用性: Unix。

3.3 新版功能.

time.clock_settime_ns(clk_id, time: int)?

與 clock_settime() 相似，但設置時間為納秒。

可用性: Unix。

3.7 新版功能.

time.ctime([secs])?

Convert a time expressed in seconds since the epoch to a string of a form: 'Sun Jun 20 23:21:05 1993' representing local time. The day field is two characters long and is space padded if the day is a single digit, e.g.: 'Wed Jun  9 04:26:40 1993'.

如果 secs 未提供或為 None，則使用 time() 所返回的當前時間。 ctime(secs) 等價于 asctime(localtime(secs))。 ctime() 不會使用區(qū)域設置信息。

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 常量 。

• monotonic ：如果時鐘不能倒退，則為 True ，否則為 False 。

• resolution ： 以秒為單位的時鐘分辨率（ float ）

3.3 新版功能.

time.gmtime([secs])?

Convert a time expressed in seconds since the epoch to a struct_time in UTC in which the dst flag is always zero. If secs is not provided or None, the current time as returned by time() is used. Fractions of a second are ignored. See above for a description of the struct_time object. See calendar.timegm() for the inverse of this function.

time.localtime([secs])?

與 gmtime() 相似但轉換為當地時間。如果未提供 secs 或為 None ，則使用由 time() 返回的當前時間。當 DST 適用于給定時間時，dst標志設置為 1 。

localtime() may raise OverflowError, if the timestamp is outside the range of values supported by the platform C localtime() or gmtime() functions, and OSError on localtime() or gmtime() failure. It's common for this to be restricted to years between 1970 and 2038.

time.mktime(t)?

這是 localtime() 的反函數。它的參數是 struct_time 或者完整的 9 元組（因為需要 dst 標志；如果它是未知的則使用 -1 作為dst標志），它表示 local 的時間，而不是 UTC 。它返回一個浮點數，以便與 time() 兼容。如果輸入值不能表示為有效時間，則 OverflowError 或 ValueError 將被引發(fā)（這取決于Python或底層C庫是否捕獲到無效值）。它可以生成時間的最早日期取決于平臺。

time.monotonic() → float?

（以小數表示的秒為單位）返回一個單調時鐘的值，即不能倒退的時鐘。 該時鐘不受系統時鐘更新的影響。 返回值的參考點未被定義，因此只有兩次調用之間的差值才是有效的。

使用 monotonic_ns() 以避免 float 類型導致的精度損失。

3.3 新版功能.

在 3.5 版更改: 該功能現在始終可用且始終在系統范圍內。

在 3.10 版更改: 在 macOS 上，現在這個函數作用于全系統。

time.monotonic_ns() → int?

與 monotonic() 相似，但是返回時間為納秒數。

3.7 新版功能.

time.perf_counter() → float?

（以小數表示的秒為單位）返回一個性能計數器的值，即用于測量較短持續(xù)時間的具有最高有效精度的時鐘。 它會包括睡眠狀態(tài)所消耗的時間并且作用于全系統范圍。 返回值的參考點未被定義，因此只有兩次調用之間的差值才是有效的。

使用 perf_counter_ns() 以避免 float 類型導致的精度損失。

3.3 新版功能.

在 3.10 版更改: 在 Windows 上，現在這個函數作用于全系統。

time.perf_counter_ns() → int?

與 perf_counter() 相似，但是返回時間為納秒。

3.7 新版功能.

time.process_time() → float?

（以小數表示的秒為單位）返回當前進程的系統和用戶 CPU 時間的總計值。 它不包括睡眠狀態(tài)所消耗的時間。 根據定義它只作用于進程范圍。 返回值的參考點未被定義，因此只有兩次調用之間的差值才是有效的。

使用 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 floating point number to indicate a more precise sleep time.

If the sleep is interrupted by a signal and no exception is raised by the signal handler, the sleep is restarted with a recomputed timeout.

The suspension time may be longer than requested by an arbitrary amount, because of the scheduling of other activity in the system.

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:

• Use clock_nanosleep() if available (resolution: 1 nanosecond);

• Or use nanosleep() if available (resolution: 1 nanosecond);

• Or use select() (resolution: 1 microsecond).

在 3.11 版更改: On Unix, the clock_nanosleep() and nanosleep() functions are now used if available. On Windows, a waitable timer is now used.

在 3.5 版更改: 現在，即使該睡眠過程被信號中斷，該函數也會保證調用它的線程至少會睡眠 secs 秒。信號處理例程拋出異常的情況除外。（欲了解我們做出這次改變的原因，請參見 PEP 475 ）

time.strftime(format[, t])?

轉換一個元組或 struct_time 表示的由 gmtime() 或 localtime() 返回的時間到由 format 參數指定的字符串。如果未提供 t ，則使用由 localtime() 返回的當前時間。 format 必須是一個字符串。如果 t 中的任何字段超出允許范圍，則引發(fā) ValueError 。

0是時間元組中任何位置的合法參數；如果它通常是非法的，則該值被強制改為正確的值。

以下指令可以嵌入 format 字符串中。它們顯示時沒有可選的字段寬度和精度規(guī)范，并被 strftime() 結果中的指示字符替換：

指令	含意	備注
%a	本地化的縮寫星期中每日的名稱。
%A	本地化的星期中每日的完整名稱。
%b	本地化的月縮寫名稱。
%B	本地化的月完整名稱。
%c	本地化的適當日期和時間表示。
%d	十進制數 [01,31] 表示的月中日。
%H	十進制數 [00,23] 表示的小時（24小時制）。
%I	十進制數 [01,12] 表示的小時（12小時制）。
%j	十進制數 [001,366] 表示的年中日。
%m	十進制數 [01,12] 表示的月。
%M	十進制數 [00,59] 表示的分鐘。
%p	本地化的 AM 或 PM 。	(1)
%S	十進制數 [00,61] 表示的秒。	(2)
%U	十進制數 [00,53] 表示的一年中的周數（星期日作為一周的第一天）。 在第一個星期日之前的新年中的所有日子都被認為是在第 0 周。	(3)
%w	十進制數 [0(星期日),6] 表示的周中日。
%W	十進制數 [00,53] 表示的一年中的周數（星期一作為一周的第一天）。 在第一個星期一之前的新年中的所有日子被認為是在第 0 周。	(3)
%x	本地化的適當日期表示。
%X	本地化的適當時間表示。
%y	十進制數 [00,99] 表示的沒有世紀的年份。
%Y	十進制數表示的帶世紀的年份。
%z	Time zone offset indicating a positive or negative time difference from UTC/GMT of the form +HHMM or -HHMM, where H represents decimal hour digits and M represents decimal minute digits [-23:59, +23:59]. 1
%Z	Time zone name (no characters if no time zone exists). Deprecated. 1
%%	字面的 '%' 字符。

注釋：

1. 當與 strptime() 函數一起使用時，如果使用 %I 指令來解析小時， %p 指令只影響輸出小時字段。

2. 范圍真的是 0 到 61 ；值 60 在表示 leap seconds 的時間戳中有效，并且由于歷史原因支持值 61 。

3. 當與 strptime() 函數一起使用時， %U 和 %W 僅用于指定星期幾和年份的計算。

Here is an example, a format for dates compatible with that specified in the RFC 2822 Internet email standard. 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) 文檔。

在某些平臺上，可選的字段寬度和精度規(guī)范可以按照以下順序緊跟在指令的初始 '%' 之后；這也不可移植。字段寬度通常為2，除了 %j ，它是3。

time.strptime(string[, format])?

根據格式解析表示時間的字符串。 返回值為一個被 gmtime() 或 localtime() 返回的 struct_time 。

format 參數使用與 strftime() 相同的指令。 它默認為匹配 ctime() 所返回的格式 "%a %b %d %H:%M:%S %Y"` 。 如果 string 不能根據 format 來解析，或者解析后它有多余的數據，則會引發(fā) 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 是否為真。因此，它是特定于平臺的，除了識別始終已知的 UTC 和 GMT （并且被認為是非夏令時時區(qū)）。

僅支持文檔中指定的指令。因為每個平臺都實現了 strftime() ，它有時會提供比列出的指令更多的指令。但是 strptime() 獨立于任何平臺，因此不一定支持所有未記錄為支持的可用指令。

class time.struct_time?

返回的時間值序列的類型為 gmtime() 、 localtime() 和 strptime() 。它是一個帶有 named tuple 接口的對象：可以通過索引和屬性名訪問值。 存在以下值：

索引	屬性	值
0	tm_year	（例如，1993）
1	tm_mon	range [1, 12]
2	tm_mday	range [1, 31]
3	tm_hour	range [0, 23]
4	tm_min	range [0, 59]
5	tm_sec	range [0, 61]； 見 strftime() 介紹中的 (2)
6	tm_wday	range [0, 6] ，周一為 0
7	tm_yday	range [1, 366]
8	tm_isdst	0, 1 或 -1；如下所示
N/A	tm_zone	時區(qū)名稱的縮寫
N/A	tm_gmtoff	以秒為單位的UTC以東偏離

請注意，與C結構不同，月份值是 [1,12] 的范圍，而不是 [0,11] 。

在調用 mktime() 時， tm_isdst 可以在夏令時生效時設置為1，而在夏令時不生效時設置為0。 值-1表示這是未知的，并且通常會導致填寫正確的狀態(tài)。

當一個長度不正確的元組被傳遞給期望 struct_time 的函數，或者具有錯誤類型的元素時，會引發(fā) TypeError 。

time.time() → float?

Return the time in seconds since the epoch as a floating point number. The handling of leap seconds is platform dependent. On Windows and most Unix systems, the leap seconds are not counted towards the time in seconds since the epoch. This is commonly referred to as Unix time.

請注意，即使時間總是作為浮點數返回，但并非所有系統都提供高于1秒的精度。雖然此函數通常返回非遞減值，但如果在兩次調用之間設置了系統時鐘，則它可以返回比先前調用更低的值。

返回的數字 time() 可以通過將其傳遞給 gmtime() 函數或轉換為UTC中更常見的時間格式（即年、月、日、小時等）或通過將它傳遞給 localtime() 函數獲得本地時間。在這兩種情況下都返回一個 struct_time 對象，日歷日期組件可以從中作為屬性訪問。

使用 time_ns() 以避免 float 類型導致的精度損失。

time.time_ns() → int?

與 time() 相似，但返回時間為用整數表示的自 epoch 以來所經過的納秒數。

3.7 新版功能.

time.thread_time() → float?

（以小數表示的秒為單位）返回當前線程的系統和用戶 CPU 時間的總計值。 它不包括睡眠狀態(tài)所消耗的時間。 根據定義它只作用于線程范圍。 返回值的參考點未被定義，因此只有兩次調用之間的差值才是有效的。

使用 thread_time_ns() 以避免 float 類型導致的精度損失。

可用性 ： Windows、 Linux、 Unix 系統支持 CLOCK_THREAD_CPUTIME_ID 。

3.7 新版功能.

time.thread_time_ns() → int?

與 thread_time() 相似，但返回納秒時間。

3.7 新版功能.

time.tzset()?

重置庫例程使用的時間轉換規(guī)則。環(huán)境變量 TZ 指定如何完成。它還將設置變量 tzname （來自 TZ 環(huán)境變量）， timezone （UTC的西部非DST秒）， altzone （UTC以西的DST秒）和 daylight （如果此時區(qū)沒有任何夏令時規(guī)則則為0，如果有夏令時適用的時間，無論過去、現在或未來，則為非零）。

可用性: Unix。

備注

雖然在很多情況下，更改 TZ 環(huán)境變量而不調用 tzset() 可能會影響函數的輸出，例如 localtime() ，不應該依賴此行為。

TZ 不應該包含空格。

TZ 環(huán)境變量的標準格式是（為了清晰起見，添加了空格）:

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

組件的位置是：

std 和 dst

三個或更多字母數字，給出時區(qū)縮寫。這些將傳到 time.tzname

offset

偏移量的形式為： ± hh[:mm[:ss]] 。這表示添加到達UTC的本地時間的值。如果前面有 '-' ，則時區(qū)位于本初子午線的東邊；否則，在它是西邊。如果dst之后沒有偏移，則假設夏令時比標準時間提前一小時。

start[/time], end[/time]

指示何時更改為DST和從DST返回。開始日期和結束日期的格式為以下之一：

Jn

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

n

從零開始的Julian日（0 <= n <= 365）。 閏日計入，可以引用2月29日。

Mm.n.d

一年中 m 月的第 n 周（1 <= n <= 5 ，1 <= m <= 12 ，第 5 周表示 “可能在 m 月第 4 周或第 5 周出現的最后第 d 日”）的第 d 天（0 <= d <= 6）。 第 1 周是第 d 天發(fā)生的第一周。 第 0 天是星期天。

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 上），使用系統的區(qū)域信息（ tzfile(5) ）數據庫來指定時區(qū)規(guī)則會更方便。為此，將 TZ 環(huán)境變量設置為所需時區(qū)數據文件的路徑，相對于系統 'zoneinfo' 時區(qū)數據庫的根目錄，通常位于 /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')

Clock ID 常量?

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

time.CLOCK_BOOTTIME?

與 CLOCK_MONOTONIC 相同，除了它還包括系統暫停的任何時間。

這允許應用程序獲得一個暫停感知的單調時鐘，而不必處理 CLOCK_REALTIME 的復雜性，如果使用 settimeofday() 或類似的時間更改時間可能會有不連續(xù)性。

可用性: Linux 2.6.39 或更新

3.7 新版功能.

time.CLOCK_HIGHRES?

Solaris OS 有一個 CLOCK_HIGHRES 計時器，試圖使用最佳硬件源，并可能提供接近納秒的分辨率。 CLOCK_HIGHRES 是不可調節(jié)的高分辨率時鐘。

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

該時間的絕對值是系統運行且未暫停的時間，提供準確的正常運行時間測量，包括絕對值和間隔值。

可用性: FreeBSD， OpenBSD 5.5 或更新。

3.7 新版功能.

time.CLOCK_UPTIME_RAW?

單調遞增的時鐘，記錄從一個任意起點開始的時間，不受頻率或時間調整的影響，并且當系統休眠時將不會遞增。

可用性: macOS 10.12 和更新版本。

3.8 新版功能.

以下常量是唯一可以發(fā)送到 clock_settime() 的參數。

time.CLOCK_REALTIME?

系統范圍的實時時鐘。 設置此時鐘需要適當的權限。

可用性: Unix。

3.3 新版功能.

時區(qū)常量?

time.altzone?

本地DST時區(qū)的偏移量，以UTC為單位的秒數，如果已定義。如果當地DST時區(qū)在UTC以東（如在西歐，包括英國），則是負數。 只有當 daylight 非零時才使用它。 見下面的注釋。

time.daylight?

如果定義了DST時區(qū)，則為非零。 見下面的注釋。

time.timezone?

本地（非DST）時區(qū)的偏移量，UTC以西的秒數（西歐大部分地區(qū)為負，美國為正，英國為零）。 見下面的注釋。

time.tzname?

兩個字符串的元組：第一個是本地非DST時區(qū)的名稱，第二個是本地DST時區(qū)的名稱。 如果未定義DST時區(qū)，則不應使用第二個字符串。 見下面的注釋。

備注

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.