time — 时间访问与转换¶
此模块提供各种与时间相关的函数。有关相关功能，另请参阅 datetime 和 calendar 模块。
尽管此模块始终可用，但并非所有函数都在所有平台上可用。此模块中定义的大多数函数都调用同名的平台 C 库函数。查阅平台文档有时可能会有帮助，因为这些函数的语义因平台而异。
一些术语和惯例的解释如下。
纪元 是时间开始的点，即
time.gmtime(0)的返回值。在所有平台上，它都是 1970 年 1 月 1 日 00:00:00 (UTC)。
术语 自纪元以来的秒数 指自纪元以来经过的总秒数，通常不包括 闰秒。在所有符合 POSIX 标准的平台上，闰秒都从总数中排除。
此模块中的函数可能无法处理 纪元 之前或遥远未来的日期和时间。未来的截止点由 C 库决定；对于 32 位系统，通常在 2038 年。
函数
strptime()在给定%y格式代码时可以解析 2 位年份。当解析 2 位年份时，它们根据 POSIX 和 ISO C 标准进行转换：值 69–99 映射到 1969–1999，值 0–68 映射到 2000–2068。
DST 是夏令时，它在一年中的部分时间将时区调整（通常）一小时。DST 规则是神奇的（由当地法律决定），并且每年都可能变化。C 库有一个包含当地规则的表（通常从系统文件读取以实现灵活性），并且是这方面唯一真正的智慧来源。
各种实时函数的精度可能低于其值或参数所表达的单位所暗示的精度。例如，在大多数 Unix 系统上，时钟每秒“嘀嗒”仅 50 或 100 次。
另一方面，
time()和sleep()的精度优于其 Unix 等效项：时间以浮点数表示，time()返回可用的最准确时间（在可用时使用 Unixgettimeofday()），并且sleep()将接受带非零小数的时间（在可用时使用 Unixselect()实现）。由
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在 UTC纪元以来的秒数
struct_time在本地时间struct_time在 UTC纪元以来的秒数
struct_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()不使用区域设置信息。备注
与同名的 C 函数不同，
asctime()不添加尾随换行符。
- time.pthread_getcpuclockid(thread_id)¶
返回指定 thread_id 的线程特定 CPU 时间时钟的 clk_id。
使用
threading.get_ident()或threading.Thread对象的ident属性来获取适用于 thread_id 的值。警告
传递无效或已过期的 thread_id 可能会导致未定义行为，例如段错误。
可用性：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()，但以纳秒为单位返回时间。可用性: Unix。
在 3.7 版本加入。
- time.clock_settime(clk_id, time: float)¶
设置指定时钟 clk_id 的时间。目前，
CLOCK_REALTIME是 clk_id 唯一接受的值。使用
clock_settime_ns()以避免由float类型引起的精度损失。可用性：Unix，不包括 Android，不包括 iOS。
在 3.3 版本加入。
- time.clock_settime_ns(clk_id, time: int)¶
类似于
clock_settime()，但以纳秒设置时间。可用性：Unix，不包括 Android，不包括 iOS。
在 3.7 版本加入。
- time.ctime([secs])¶
将自 纪元 以来的秒数表示的时间转换为以下形式的字符串：
'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，否则为Falseresolution: 时钟的以秒为单位的分辨率 (
float)
在 3.3 版本加入。
- time.gmtime([secs])¶
将自 纪元 以来的秒数表示的时间转换为 UTC 中的
struct_time，其中 dst 标志始终为零。如果未提供 secs 或其值为None，则使用time()返回的当前时间。忽略秒的小数部分。有关struct_time对象的描述，请参阅上文。有关此函数的逆操作，请参阅calendar.timegm()。
- time.localtime([secs])¶
类似于
gmtime()，但转换为本地时间。如果未提供 secs 或其值为None，则使用time()返回的当前时间。当夏令时适用于给定时间时，dst 标志设置为1。如果时间戳超出了平台 C
localtime()或gmtime()函数支持的值范围，localtime()可能会引发OverflowError，并且在localtime()或gmtime()失败时引发OSError。这通常限制在 1970 年到 2038 年之间。
- time.mktime(t)¶
这是
localtime()的逆函数。其参数是struct_time或完整的 9 元组（因为需要 dst 标志；如果未知，使用-1作为 dst 标志），它以 本地 时间（而非 UTC）表示时间。它返回一个浮点数，以与time()兼容。如果输入值无法表示为有效时间，将引发OverflowError或ValueError（具体取决于无效值是由 Python 捕获还是由底层 C 库捕获）。它可以生成时间的最早日期取决于平台。
- time.monotonic() float¶
返回单调时钟的值（以小数秒为单位），即不能倒退的时钟。该时钟不受系统时钟更新的影响。返回值的参考点未定义，因此只有两次调用结果之间的差异才有效。
时钟
在 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 实现细节: 在 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)¶
暂停调用线程的执行，持续给定秒数。参数可以是浮点数，以指示更精确的睡眠时间。
如果睡眠被信号中断，且信号处理程序未引发异常，则会重新计算超时时间并重新开始睡眠。
由于系统中其他活动的调度，暂停时间可能会任意长于请求时间。
Windows 实现
在 Windows 上，如果 secs 为零，线程会将剩余的时间片让给任何准备运行的其他线程。如果没有其他线程准备运行，函数会立即返回，并且线程继续执行。在 Windows 8.1 及更高版本上，实现使用 高分辨率计时器，它提供 100 纳秒的分辨率。如果 secs 为零，则使用
Sleep(0)。Unix 实现
如果可用，使用
clock_nanosleep()（分辨率：1 纳秒）；或者，如果可用，使用
nanosleep()（分辨率：1 纳秒）；或者，使用
select()（分辨率：1 微秒）。
引发一个 审计事件
time.sleep，参数为secs。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区域设置的缩写工作日名称。
%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 表示十进制小时数字，M 表示十进制分钟数字 [-23:59, +23:59]。[1]
%Z时区名称（如果不存在时区，则无字符）。已弃用。[1]
%GISO 8601 年份（类似于
%Y，但遵循 ISO 8601 日历年的规则）。年份从包含日历年第一个周四的那一周开始。%VISO 8601 周数（以十进制数字 [01,53] 表示）。一年中的第一周是包含该年第一个周四的那一周。周一是一周的开始。
%%字面上的
'%'字符。备注
%f格式指令仅适用于strptime()，不适用于strftime()。但是，另请参阅datetime.datetime.strptime()和datetime.datetime.strftime()，其中%f格式指令 适用于微秒。与
strptime()函数一起使用时，%p指令仅在%I指令用于解析小时时才影响输出小时字段。
范围确实是
0到61；值60在表示 闰秒 的时间戳中有效，值61为历史原因而支持。与
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) 文档。
在某些平台上，可选的字段宽度和精度规范可以紧跟在指令的初始
'%'之后，顺序如下；这也不具有可移植性。除了%j之外，字段宽度通常为 2，%j为 3。
- time.strptime(string[, format])¶
根据格式解析表示时间的字符串。返回值是
gmtime()或localtime()返回的struct_time。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()返回的时间值序列的类型。它是一个具有 命名元组 接口的对象：可以通过索引和属性名称访问值。存在以下值索引
属性
值
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；见下文
不适用
- tm_zone¶
时区名称缩写
不适用
- tm_gmtoff¶
UTC 以东的偏移量，以秒为单位
请注意，与 C 结构不同，月份值范围是 [1, 12]，而不是 [0, 11]。
在调用
mktime()时，当夏令时生效时，tm_isdst可以设置为 1，不生效时设置为 0。值为 -1 表示未知，通常会导致填充正确的状态。当将长度不正确或元素类型不正确的元组传递给期望
struct_time的函数时，将引发TypeError。
- time.time() float¶
以浮点数形式返回自 纪元 以来的秒数。 闰秒 的处理取决于平台。在 Windows 和大多数 Unix 系统上，闰秒不计入自 纪元 以来的秒数。这通常被称为 Unix 时间。
请注意，即使时间总是以浮点数返回，并非所有系统都提供比 1 秒更精确的时间。虽然此函数通常返回非递减值，但如果系统时钟在两次调用之间被设置回，它可能会返回低于上次调用的值。
由
time()返回的数字可以通过将其传递给gmtime()函数转换为 UTC 中的更常见时间格式（即年、月、日、小时等），或通过将其传递给localtime()函数转换为本地时间。在这两种情况下，都会返回一个struct_time对象，可以从中以属性形式访问日历日期的组成部分。时钟
在 Windows 上，调用
GetSystemTimePreciseAsFileTime()。如果可用，调用
clock_gettime(CLOCK_REALTIME)。否则，调用
gettimeofday()。
3.13 版本中已更改: 在 Windows 上，调用 GetSystemTimePreciseAsFileTime() 而不是 GetSystemTimeAsFileTime()。
- time.thread_time() float¶
返回当前线程的系统和用户 CPU 时间之和（以小数秒为单位）。它不包括睡眠期间经过的时间。根据定义，它是线程特定的。返回值的参考点未定义，因此只有同一线程中两次调用结果之间的差异才有效。
使用
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()¶
重置库例程使用的时间转换规则。环境变量
TZ指定了如何执行此操作。它还将设置变量tzname（来自TZ环境变量）、timezone（非 DST 秒，西经 UTC）、altzone（DST 秒，西经 UTC）和daylight（如果及时区没有任何夏令时规则，则为 0；如果过去、现在或将来有夏令时适用，则为非零）。可用性: Unix。
TZ环境变量的标准格式是（为清晰起见添加了空格）std offset [dst [offset [,start[/time], end[/time]]]]
其中组件为
std和dst三个或更多字母数字字符，给出时区缩写。这些将传播到 time.tzname
偏移偏移量格式为：
± hh[:mm[:ss]]。这表示添加到本地时间以到达 UTC 的值。如果前面有“−”，则时区位于本初子午线以东；否则，它位于西部。如果 dst 后没有偏移量，则夏季时间假定比标准时间提前一小时。start[/time], end[/time]指示何时转换为夏令时以及何时从夏令时转换回来。开始和结束日期的格式是以下之一
Jn儒略日 n (1 <= n <= 365)。闰日不计算在内，因此在所有年份中，2 月 28 日是第 59 天，3 月 1 日是第 60 天。
n基于零的儒略日（0 <= n <= 365）。闰日被计算在内，并且可以指代 2 月 29 日。
Mm.n.d一年中第 m 月的第 n 周的第 d 天 (0 <= d <= 6) (1 <= n <= 5, 1 <= m <= 12，其中第 5 周表示“m 月的最后一个 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_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_UPTIME_RAW¶
单调递增的时钟，跟踪自任意点以来的时间，不受频率或时间调整的影响，并且在系统休眠时不递增。
可用性：macOS >= 10.12。
在 3.8 版本加入。
- time.CLOCK_UPTIME_RAW_APPROX¶
类似于
CLOCK_UPTIME_RAW，但该值在上下文切换时由系统缓存，因此精度较低。可用性：macOS >= 10.12。
在 3.13 版本加入。
以下常量是唯一可以发送给 clock_settime() 的参数。
时区常量¶
- time.altzone¶
如果定义了本地夏令时时区，则为该时区相对于 UTC 西边的秒数偏移量。如果本地夏令时时区在 UTC 的东边（例如西欧，包括英国），则此值为负数。仅当
daylight非零时才使用此值。请参阅下面的注释。
- time.daylight¶
如果定义了夏令时时区，则为非零值。请参阅下面的注释。
- time.timezone¶
本地（非夏令时）时区相对于 UTC 西边的秒数偏移量（在大多数西欧为负数，在美国为正数，在英国为零）。请参阅下面的注释。
- time.tzname¶
一个包含两个字符串的元组：第一个是本地非夏令时时区的名称，第二个是本地夏令时时区的名称。如果未定义夏令时时区，则不应使用第二个字符串。请参阅下面的注释。
备注
对于上述时区常量（altzone、daylight、timezone 和 tzname），其值由模块加载时或最后一次调用 tzset() 时生效的时区规则确定，并且可能与过去的时间不符。建议使用 localtime() 的 tm_gmtoff 和 tm_zone 结果来获取时区信息。
参见
- 模块
datetime 更面向对象的日期和时间接口。
- 模块
locale 国际化服务。区域设置会影响
strftime()和strptime()中许多格式说明符的解释。- 模块
calendar
脚注