time --- 时间的访问和转换¶
该模块提供了各种与时间相关的函数。相关功能还可以参阅 datetime 和 calendar 模块。
尽管所有平台皆可使用此模块，但模块内的函数并非所有平台都可用。此模块中定义的大多数函数的实现都是调用其所在平台的C语言库的同名函数。因为这些函数的语义可能因平台而异，所以使用时最好查阅对应平台的相关文档。
下面是一些术语和惯例的解释.
epoch 是起始的时间点，即
time.gmtime(0)的返回值。 这在所有平台上都是 1970-01-01, 00:00:00 (UTC)。
术语 纪元秒数 是指自 epoch （纪元）时间点以来经过的总秒数，通常不包括 闰秒。 在所有符合 POSIX 标准的平台上，闰秒都不会记录在总秒数中。
此模块中的函数可能无法处理 epoch 之前或遥远未来的日期和时间。 “遥远未来”的分界点是由 C 库确定的；对于 32 位系统，它通常是在 2038 年。
函数
strptime()在接收到%y格式代码时可以解析使用 2 位数表示的年份。当解析 2 位数年份时，函数会按照 POSIX 和 ISO C 标准进行年份转换：数值 69--99 被映射为 1969--1999；数值 0--68 被映射为 2000--2068。
UTC是协调世界时（Coordinated Universal Time）的缩写。它以前也被称为格林威治标准时间（GMT）。使用UTC而不是CUT作为缩写是英语与法语（Temps Universel Coordonné）之间妥协的结果，不是什么低级错误。
DST是夏令时（Daylight Saving Time）的缩写，在一年的某一段时间中将当地时间调整（通常）一小时。 DST的规则非常神奇（由当地法律确定），并且每年的起止时间都不同。C语言库中有一个表格，记录了各地的夏令时规则（实际上，为了灵活性，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现在可在所有平台上使用。使用以下函数在时间表示之间进行转换：
从
到
使用
自纪元以来的秒数
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.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])¶
将以距离 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 常量 。
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。localtime()可能会引发OverflowError，如果时间戳超出平台 Clocaltime()或gmtime()函数支持的范围，并会在localtime()或gmtime()失败时引发OSError。这通常被限制在1970至2038年之间。
- time.mktime(t)¶
这是
localtime()的反函数。它的参数是struct_time或者完整的 9 元组（因为需要 dst 标志；如果它是未知的则使用-1作为dst标志），它表示 local 的时间，而不是 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)¶
调用方线程暂停执行给定的秒数。 该参数可以为浮点数以指定一个更精确的休眠时间。
如果休眠被信号打断并且信号处理句柄未引发异常，休眠将基于重新计算的时延重新开始。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.
暂停时间有可能比请求的要长出一段不确定的时间，因为会受系统中的其他活动排期影响。
在 Windows 上，如果 secs 为零，线程会将其时间片的剩余部分让渡给任何其他准备要运行的线程。 如果没有准备要运行的其他线程，该函数将立即返回，而线程将继续执行。 在 Windows 8.1 及更新版本中的实现使用了提供 100 纳秒分辨率的 高分辨率定时器。 如果 secs 为零，则会使用
Sleep(0)。Unix 实现:
如果可能则使用
clock_nanosleep()(精度: 1 纳秒);或者如果可能则使用
nanosleep()(精度: 1 纳秒);或者使用
select()(精度: 1 微秒).
在 3.11 版更改: 在 Unix 上，现在将在可能的情况下使用
clock_nanosleep()和nanosleep()函数。 在 Windows 上，现在将使用可等待的计时器。在 3.5 版更改: 现在，即使该睡眠过程被信号中断，该函数也会保证调用它的线程至少会睡眠 secs 秒。信号处理例程抛出异常的情况除外。（欲了解我们做出这次改变的原因，请参见 PEP 475 ）
- time.strftime(format[, t])¶
转换一个元组或
struct_time表示的由gmtime()或localtime()返回的时间到由 format 参数指定的字符串。如果未提供 t ，则使用由localtime()返回的当前时间。 format 必须是一个字符串。如果 t 中的任何字段超出允许范围，则引发ValueError。0是时间元组中任何位置的合法参数；如果它通常是非法的，则该值被强制改为正确的值。
以下指令可以嵌入 format 字符串中。它们显示时没有可选的字段宽度和精度规范，并被
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时区偏移以格式 +HHMM 或 -HHMM 形式的 UTC/GMT 的正或负时差指示，其中H表示十进制小时数字，M表示小数分钟数字 [-23:59, +23:59] 。1
%Z时区名称（如果不存在时区，则不包含字符）。已弃用。 1
%%字面的
'%'字符。注释：
当与
strptime()函数一起使用时，如果使用%I指令来解析小时，%p指令只影响输出小时字段。
范围真的是
0到61；值60在表示 leap seconds 的时间戳中有效，并且由于历史原因支持值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()相同的指令。 它默认为匹配ctime()所返回的格式"%a %b %d %H:%M:%S %Y"`。 如果 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是否为真。因此，它是特定于平台的，除了识别始终已知的 UTC 和 GMT （并且被认为是非夏令时时区）。仅支持文档中指定的指令。因为每个平台都实现了
strftime()，它有时会提供比列出的指令更多的指令。但是strptime()独立于任何平台，因此不一定支持所有未记录为支持的可用指令。
- class time.struct_time¶
返回的时间值序列的类型为
gmtime()、localtime()和strptime()。它是一个带有 named tuple 接口的对象：可以通过索引和属性名访问值。 存在以下值：索引
属性
值
0
- tm_year¶
（例如，1993）
1
- tm_mon¶
range [1, 12]
2
- tm_day¶
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¶
取值范围 [0, 6]；周一为 0
7
- tm_yday¶
range [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.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
offset偏移量的形式为：
± hh[:mm[:ss]]。这表示添加到达UTC的本地时间的值。如果前面有 '-' ，则时区位于本初子午线的东边；否则，在它是西边。如果dst之后没有偏移，则假设夏令时比标准时间提前一小时。start[/time], end[/time]指示何时更改为DST和从DST返回。开始日期和结束日期的格式为以下之一：
JnJulian日 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 天发生的第一周。 第 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 上），使用系统的区域信息（ 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')
Clock ID 常量¶
这些常量用作 clock_getres() 和 clock_gettime() 的参数。
- time.CLOCK_BOOTTIME¶
与
CLOCK_MONOTONIC相同，除了它还包括系统暂停的任何时间。这允许应用程序获得一个暂停感知的单调时钟，而不必处理
CLOCK_REALTIME的复杂性，如果使用settimeofday()或类似的时间更改时间可能会有不连续性。可用性: Linux >= 2.6.39。
3.7 新版功能.
- time.CLOCK_HIGHRES¶
Solaris OS 有一个
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_UPTIME¶
该时间的绝对值是系统运行且未暂停的时间，提供准确的正常运行时间测量，包括绝对值和间隔值。
可用性: FreeBSD, OpenBSD >= 5.5。
3.7 新版功能.
- time.CLOCK_UPTIME_RAW¶
单调递增的时钟，记录从一个任意起点开始的时间，不受频率或时间调整的影响，并且当系统休眠时将不会递增。
可用性: macOS >= 10.12。
3.8 新版功能.
以下常量是唯一可以发送到 clock_settime() 的参数。
时区常量¶
- 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 来获取时区信息。
参见
- 模块
datetime 更多面向对象的日期和时间接口。
- 模块
locale 国际化服务。 区域设置会影响
strftime()和strptime()中许多格式说明符的解析。- 模块
calendar 一般日历相关功能。这个模块的
timegm()是函数gmtime()的反函数。
备注