time — 时间访问和转换¶
此模块提供了各种与时间相关的函数。有关相关功能，另请参阅 datetime 和 calendar 模块。
尽管此模块始终可用，但并非所有函数都可以在所有平台上使用。此模块中定义的大多数函数都调用具有相同名称的平台 C 库函数。有时查阅平台文档可能会有所帮助，因为这些函数的语义在不同平台之间有所不同。
有必要解释一些术语和约定。
纪元是时间开始的点，是
time.gmtime(0)的返回值。它在所有平台上都是 1970 年 1 月 1 日 00:00:00 (UTC)。
术语自纪元以来的秒数指的是自纪元以来经过的总秒数，通常不包括闰秒。在所有符合 POSIX 的平台上，闰秒都将从该总数中排除。
此模块中的函数可能无法处理 纪元之前或遥远未来的日期和时间。未来的截止点由 C 库决定；对于 32 位系统，它通常在 2038 年。
当给定
%y格式代码时，函数strptime()可以解析 2 位数的年份。当解析 2 位数的年份时，它们会根据 POSIX 和 ISO C 标准进行转换：值 69-99 映射到 1969-1999，值 0-68 映射到 2000-2068。
UTC 是协调世界时（以前称为格林威治标准时间或 GMT）。首字母缩略词 UTC 不是错误，而是英语和法语之间的折衷。
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_time类型已扩展为在平台支持相应的struct tm成员时提供tm_gmtoff和tm_zone属性。在 3.6 版本中更改: 现在在所有平台上都可以使用
struct_time属性tm_gmtoff和tm_zone。使用以下函数在时间表示形式之间进行转换
从
到
使用
自纪元以来的秒数
UTC 中的
struct_time自纪元以来的秒数
当地时间中的
struct_timeUTC 中的
struct_time自纪元以来的秒数
当地时间中的
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()或ident属性的threading.Thread对象，以获取适合 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* 的时间。目前，*clk_id* 仅接受
CLOCK_REALTIME这一个值。使用
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: 如果时钟可以自动更改（例如，通过 NTP 守护程序）或由系统管理员手动更改，则为
True，否则为Falseimplementation: 用于获取时钟值的底层 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 应用于给定时间时，dst 标志设置为1。如果时间戳超出平台 C
localtime()或gmtime()函数支持的值范围，localtime()可能会引发OverflowError，并且如果localtime()或gmtime()失败，则可能会引发OSError。通常，这会被限制在 1970 年到 2038 年之间。
- time.mktime(t)¶
这是
localtime()的反函数。它的参数是struct_time或完整的 9 元组（因为需要 dst 标志；如果 dst 标志未知，则使用-1），它以本地时间（而不是 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 上，如果 secs 为零，则线程会将其剩余的时间片让给任何其他准备运行的线程。如果没有其他线程准备运行，则该函数会立即返回，并且该线程继续执行。在 Windows 8.1 及更高版本上，该实现使用 高分辨率计时器，它提供的分辨率为 100 纳秒。如果 secs 为零，则使用
Sleep(0)。Unix 实现
如果可用，则使用
clock_nanosleep()（分辨率：1 纳秒）；或者，如果可用，则使用
nanosleep()（分辨率：1 纳秒）；或者，使用
select()（分辨率：1 微秒）。
引发带有参数
secs的 审计事件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区域设置的缩写工作日名称。
%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()函数一起使用时，如果使用%I指令来解析小时，则%p指令仅影响输出的小时字段。
范围实际上是
0到61；值60在表示 闰秒 的时间戳中有效，并且出于历史原因支持值61。当与
strptime()函数一起使用时，仅当指定了星期几和年份时，才会在计算中使用%U和%W。
这是一个示例，与 RFC 2822 Internet 电子邮件标准中指定的日期格式兼容。 [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) 文档。
在某些平台上，可选的字段宽度和精度规范可以紧跟在指令的初始
'%'之后，顺序如下；这也是不可移植的。字段宽度通常为 2，但%j为 3。
- time.strptime(string[, format])¶
根据格式解析表示时间的字符串。返回值是由
gmtime()或localtime()返回的struct_time。format 参数使用与
strftime()使用的相同的指令；它默认为"%a %b %d %H:%M:%S %Y"，这与ctime()返回的格式匹配。如果无法根据 format 解析 string，或者解析后有额外的数据，则会引发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]；请参阅 Note (2) 中的
strftime()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¶
返回自 纪元 以来的时间（以秒为单位），结果为浮点数。 对闰秒的处理取决于平台。 在 Windows 和大多数 Unix 系统上，闰秒不计入自纪元以来的时间（以秒为单位）。 这通常被称为 Unix 时间。
请注意，即使时间始终以浮点数返回，并非所有系统都提供优于 1 秒的精度。 虽然此函数通常返回非递减的值，但如果在两次调用之间系统时钟被调回，则它可能会返回比上一次调用更低的值。
通过将
time()返回的数字传递给gmtime()函数可以将其转换为 UTC 中更常见的时间格式（即年、月、日、小时等），或者通过将其传递给localtime()函数可以将其转换为本地时间。在这两种情况下，都会返回一个struct_time对象，可以从该对象以属性的形式访问日历日期的组成部分。时钟
在 Windows 上，调用
GetSystemTimeAsFileTime()。如果可用，调用
clock_gettime(CLOCK_REALTIME)。否则，调用
gettimeofday()。
- 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（UTC 以西的非 DST 秒数）、altzone（UTC 以西的 DST 秒数）和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相同，只是它还包括系统挂起的任何时间。这允许应用程序获取感知挂起的单调时钟，而无需处理如果使用
settimeofday()或类似方法更改时间时可能会出现不连续的CLOCK_REALTIME的复杂性。可用性：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¶
该时间的绝对值是系统运行且未挂起的时间，提供精确的正常运行时间测量，包括绝对时间和间隔时间。
可用性：FreeBSD，OpenBSD >= 5.5。
3.7 版本新增。
- 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() 时有效的时区规则确定，并且对于过去的时间可能不正确。建议使用 tm_gmtoff 和 tm_zone 从 localtime() 获取时区信息的结果。
另请参阅
- 模块
datetime 日期和时间的更面向对象的接口。
- 模块
locale 国际化服务。区域设置会影响
strftime()和strptime()中许多格式说明符的解释。- 模块
calendar
脚注