time — 时间访问和转换

该模块提供各种与时间相关的功能。有关相关功能，另请参阅 datetime 和 calendar 模块。

尽管此模块始终可用，但并非所有功能都适用于所有平台。该模块中定义的大部分函数调用同名的平台 C 库函数。有时查阅平台文档可能会有所帮助，因为这些函数的语义因平台而异。

对一些术语和约定的解释是有序的。

epoch 是时间开始的点，并且取决于平台。对于 Unix，纪元是 1970 年 1 月 1 日 00:00:00 (UTC)。要了解给定平台上的时代是什么，请查看 time.gmtime(0)。

自 epoch 以来的术语 秒是指自 epoch 以来经过的总秒数，通常不包括闰秒。在所有符合 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 库有一个包含本地规则的表（通常从系统文件中读取以提高灵活性）并且是 True Wisdom 在这方面的唯一来源。
各种实时函数的精度可能低于表示其值或参数的单位所建议的精度。例如在大多数 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_time 类型扩展为当平台支持相应的 struct tm 成员时提供 tm_gmtoff 和 tm_zone 属性.

3.6 版更改： struct_time 属性 tm_gmtoff 和 tm_zone 现在在所有平台上可用。

使用以下函数在时间表示之间进行转换：

从	到	用
自纪元以来的秒数	struct_time UTC	`gmtime()`
自纪元以来的秒数	struct_time 当地时间	`localtime()`
struct_time UTC	自纪元以来的秒数	`calendar.timegm()`
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 时间时钟的 clk_id。

使用 threading.get_ident() 或 threading.Thread 对象的 ident 属性为 thread_id 获取合适的值。

警告

传递无效或过期的 thread_id 可能会导致未定义的行为，例如分段错误。

3.7 版中的新功能。

time.clock_getres(clk_id): 返回指定时钟 clk_id 的分辨率（精度）。有关 clk_id 的可接受值列表，请参阅时钟 ID 常量。

3.3 版中的新功能。

time.clock_gettime(clk_id) → float

返回指定时钟 clk_id 的时间。有关 clk_id 的可接受值列表，请参阅时钟 ID 常量。

使用 clock_gettime_ns() 避免 float 类型造成的精度损失。

3.3 版中的新功能。

time.clock_gettime_ns(clk_id) → int: 类似于 clock_gettime() 但返回时间为纳秒。

3.7 版中的新功能。

time.clock_settime(clk_id, time: float)

设置指定时钟的时间clk_id。目前，CLOCK_REALTIME 是 clk_id 唯一可接受的值。

使用 clock_settime_ns() 避免 float 类型造成的精度损失。

3.3 版中的新功能。

time.clock_settime_ns(clk_id, time: int): 类似于 clock_settime() 但以纳秒设置时间。

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 如果时钟可以自动改变（例如由 NTP 守护进程）或由系统管理员手动，False 否则
implementation：用于获取时钟值的底层C函数的名称。有关可能的值，请参阅时钟 ID 常数。
monotonic：True如果时钟不能倒退，False否则
resolution：以秒为单位的时钟分辨率（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。

time.mktime(t): 这是 localtime() 的反函数。它的参数是 struct_time 或完整的 9 元组（因为需要 dst 标志；如果未知，则使用 -1 作为 dst 标志）表示 local[ X173X] 时间，而不是 UTC。它返回一个浮点数，以与 time() 兼容。如果输入值不能表示为有效时间，则会引发 OverflowError 或 ValueError（这取决于无效值是被 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

返回性能计数器的值（以秒为单位），即具有最高可用分辨率的时钟，用于测量短时间。它确实包括睡眠期间经过的时间，并且是系统范围的。返回值的参考点未定义，因此只有两次调用结果之间的差异才有效。

使用 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): 暂停执行调用线程给定的秒数。参数可能是一个浮点数，以指示更精确的睡眠时间。实际暂停时间可能比请求的要少，因为在执行该信号的捕获例程后，任何捕获的信号都将终止 sleep()。此外，由于系统中其他活动的调度，暂停时间可能比任意数量的请求长。

3.5 版更改：即使睡眠被信号中断，该函数现在至少睡眠秒，除非信号处理程序引发异常（请参阅 PEP 475 的基本原理）。

time.strftime(format[, t])

将表示 gmtime() 或 localtime() 返回的时间的元组或 struct_time 转换为格式指定的字符串争论。如果未提供 t，则使用 localtime() 返回的当前时间。 format 必须是字符串。如果 t 中的任何字段超出允许范围，则会引发 ValueError。

0 是时间元组中任何位置的合法参数；如果它通常是非法的，则该值将被强制为正确的值。

以下指令可以嵌入到 format 字符串中。它们显示时没有可选的字段宽度和精度规范，并由 strftime() 结果中指定的字符替换：

指示	意义	笔记
`%a`	语言环境的缩写工作日名称。
`%A`	区域设置的完整工作日名称。
`%b`	语言环境的缩写月份名称。
`%B`	语言环境的完整月份名称。
`%c`	区域设置的适当日期和时间表示。
`%d`	十进制数 [01,31] 的月份中的第几天。
`%H`	小时（24 小时制）作为十进制数 [00,23]。
`%I`	小时（12 小时制）作为十进制数 [01,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(Sunday),6]。
`%W`	一年中的周数（星期一作为一周的第一天）作为十进制数 [00,53]。新年中第一个星期一之前的所有日子都被视为第 0 周。	(3)
`%x`	区域设置的适当日期表示。
`%X`	区域设置的适当时间表示。
`%y`	没有世纪的年份作为十进制数 [00,99]。
`%Y`	以世纪为十进制数的年份。
`%z`	时区偏移量表示与 UTC/GMT 的正或负时差，格式为 +HHMM 或 -HHMM，其中 H 表示十进制小时数字，M 表示十进制分钟数字 [-23:59, +23:59]。
`%Z`	时区名称（如果不存在时区，则无字符）。
`%%`	文字 `'%'` 字符。

笔记：

当与 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() 返回的格式匹配。如果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 是否为真。因此，它是特定于平台的，除了识别始终已知的 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 系统上，纪元是 1970 年 1 月 1 日的 00:00:00 (UTC)，闰秒不计入纪元以来的时间（以秒为单位）。这通常称为 Unix 时间。要了解给定平台上的时代是什么，请查看 gmtime(0)。

请注意，即使时间总是作为浮点数返回，但并非所有系统都提供比 1 秒更精确的时间。虽然此函数通常返回非递减值，但如果系统时钟在两次调用之间已回退，则它可以返回比前一次调用低的值。

time() 返回的数字可能会转换成更常见的时间格式（即年、月、日、小时等...）通过将其传递给 gmtime() 函数或在本地时间通过将其传递给 localtime() 函数。在这两种情况下，都会返回一个 struct_time 对象，从中可以访问日历日期的组件作为属性。

使用 time_ns() 避免 float 类型造成的精度损失。

time.time_ns() → int: 与 time() 类似，但将时间作为纪元以来的纳秒整数返回。

3.7 版中的新功能。

time.thread_time() → float

返回当前线程的系统和用户 CPU 时间总和的值（以秒为单位）。它不包括睡眠期间经过的时间。根据定义，它是特定于线程的。返回值的引用点是未定义的，因此只有同一线程中两次调用的结果之间的差异才有效。

使用 thread_time_ns() 避免 float 类型造成的精度损失。

3.7 版中的新功能。

time.thread_time_ns() → int: 类似于 thread_time() 但返回时间为纳秒。

3.7 版中的新功能。

time.tzset()

重置库例程使用的时间转换规则。环境变量 TZ 指定这是如何完成的。它还将设置变量 tzname（来自 TZ 环境变量）、timezone（UTC 以西的非 DST 秒）、altzone（UTC 以西的 DST 秒）和 daylight（如果此时区没有任何夏令时规则，则为 0，如果有夏令时的过去、现在或将来的时间，则为非零值适用）。

笔记

尽管在许多情况下，更改 TZ 环境变量可能会影响 localtime() 等函数的输出而不调用 tzset()，这不应该依赖行为。

TZ 环境变量不应包含空格。

TZ 环境变量的标准格式是（为了清晰起见添加了空格）：

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

组件在哪里：

std 和 dst

给出时区缩写的三个或更多字母数字。这些将被传播到 time.tzname

offset

偏移量的格式为：± hh[:mm[:ss]]。这表示与到达 UTC 的本地时间相加的值。如果前面有“-”，则时区在本初子午线以东；否则，它是西方。如果 dst 之后没有偏移，则假定夏令时比标准时间提前 1 小时。

start[/time], end[/time]

指示何时更改为和从 DST 更改。开始日期和结束日期的格式是以下之一：

Jn: 朱利安日 n (1 <= n <= 365）。闰日不计算在内，因此在所有年份中，2 月 28 日是第 59 天，3 月 1 日是第 60 天。
n: 从零开始的儒略日 (0 <= n <= 365）。闰日是计算的，可以参考2月29日。
Mm.n.d: 这 d ' 天 (0 <= d <= 6) 周 n 月的米年 (1 <= n <= 5, 1 <= 米 <= 12，其中第 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”时区数据库的根目录，通常位于 [X198X ]。例如，'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() 或类似方法更改时间，则可能会出现不连续性。

3.7 版中的新功能。

time.CLOCK_HIGHRES: Solaris OS 有一个 CLOCK_HIGHRES 计时器，它尝试使用最佳硬件源，并且可能提供接近纳秒的分辨率。 CLOCK_HIGHRES 是不可调节的高分辨率时钟。

3.3 版中的新功能。

time.CLOCK_MONOTONIC: 无法设置的时钟，表示自某个未指定起点以来的单调时间。

3.3 版中的新功能。

time.CLOCK_MONOTONIC_RAW: 类似于 CLOCK_MONOTONIC，但提供对不受 NTP 调整影响的基于硬件的原始时间的访问。

3.3 版中的新功能。

time.CLOCK_PROCESS_CPUTIME_ID: 来自 CPU 的高分辨率每进程计时器。

3.3 版中的新功能。

time.CLOCK_PROF: 来自 CPU 的高分辨率每进程计时器。

3.7 版中的新功能。

time.CLOCK_TAI

国际原子时

系统必须有一个当前的闰秒表才能给出正确的答案。 PTP或NTP软件可以维护闰秒表。

3.9 版中的新功能。

time.CLOCK_THREAD_CPUTIME_ID: 线程特定的 CPU 时间时钟。

3.3 版中的新功能。

time.CLOCK_UPTIME: 时间的绝对值是系统已运行且未暂停的时间，提供准确的正常运行时间测量，包括绝对值和间隔时间。

3.7 版中的新功能。

time.CLOCK_UPTIME_RAW: 单调递增的时钟，从任意点开始跟踪时间，不受频率或时间调整的影响，并且在系统休眠时不递增。

3.8 版中的新功能。

以下常量是唯一可以发送到 clock_settime() 的参数。

time.CLOCK_REALTIME: 全系统实时时钟。设置此时钟需要适当的权限。

3.3 版中的新功能。

时区常量

time.altzone: 本地 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结果来获取时区信息。

也可以看看

模块日期时间: 更多面向对象的日期和时间接口。
模块语言环境: 国际化服务。区域设置会影响 strftime() 和 strptime() 中许多格式说明符的解释。
模块日历: 通用日历相关功能。 timegm() 是来自该模块的 gmtime() 的倒数。

脚注

1: 现在不推荐使用 %Z，但所有 ANSI C 库都不支持扩展到首选小时/分钟偏移量的 %z 转义。此外，严格阅读原始的 1982 RFC 822 标准要求使用两位数的年份（%y 而不是 %Y），但实践在很久以前就转移到了 4 位数的年份2000 年。在那之后，RFC 822 变得过时，4 位数字的年份首先由 RFC 1123 推荐，然后由强制规定]RFC 2822。

time — 时间访问和转换 — Python 文档

time — 时间访问和转换

职能

时钟 ID 常量

时区常量