time —- 时间的访问和转换

time —- 时间的访问和转换

该模块提供了各种时间相关的函数。相关功能还可以参阅 datetime 和 calendar 模块。

尽管此模块始终可用，但并非所有平台上都提供所有功能。此模块中定义的大多数函数调用都具有相同名称的平台C库函数。因为这些函数的语义因平台而异,所以使用时最好查阅平台相关文档。

下面是一些术语和惯例的解释.

epoch 是时间开始的点，并且取决于平台。对于Unix， epoch 是1970年1月1日00:00:00（UTC）。要找出给定平台上的 epoch ，请查看 time.gmtime(0) 。
术语 Unix 纪元秒数 是指自国际标准时间 1970 年 1 月 1 日零时以来经过的总秒数，通常不包括闰秒。在所有符合 POSIX 标准的平台上，闰秒都会从总秒数中被扣除。
此模块中的功能可能无法处理纪元之前或将来的远期日期和时间。未来的截止点由C库决定；对于32位系统，它通常在2038年。
函数 strptime() 在接收到 %y 格式代码时可以解析 2 位数的年份。当解析 2 位数年份时，会按照 POSIX 和 ISO C 标准进行转换：数值 69—99 映射为 1969—1999，而数值 0—68 被映射为 2000—2068。
UTC是协调世界时（以前称为格林威治标准时间，或GMT）。缩写UTC不是错误，而是英语和法语之间的妥协。
DST是夏令时，在一年中的一部分时间（通常）调整时区一小时。 DST规则很神奇（由当地法律确定），并且每年都会发生变化。 C 库有一个包含本地规则的表（通常是从系统文件中读取以获得灵活性），并且在这方面是True Wisdom的唯一来源。
各种实时函数的精度可能低于表示其值或参数的单位所建议的精度。例如，在大多数Unix系统上，时钟 "ticks" 仅为每秒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 tm 成员时，struct_time 类型被扩展提供 tm_gmtoff 和 tm_zone 属性。

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

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

从

到

使用

自纪元以来的秒数

UTC 的 struct_time

gmtime()

自纪元以来的秒数

本地时间的 struct_time

localtime()

UTC 的 struct_time

自纪元以来的秒数

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.pthreadgetcpuclockid(_thread_id)
返回指定的 thread_id 的特定于线程的CPU时间时钟的 clk_id 。

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

警告

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

可用性： Unix（有关详细信息，请参见 pthread_getcpuclockid(3)) 的手册页）。

3.7 新版功能.

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

Availability: Unix.

3.3 新版功能.

time.clockgettime(_clk_id) → float
返回指定 clk_id 时钟的时间。有关 clk_id 的可接受值列表，请参阅 Clock ID 常量。

Availability: Unix.

3.3 新版功能.

time.clockgettime_ns(_clk_id) → int
与 clock_gettime() 相似，但返回时间为纳秒。

Availability: Unix.

3.7 新版功能.

time.clocksettime(_clk_id, time: float)
设置指定 clk_id 时钟的时间。目前， CLOCK_REALTIME 是 clk_id 唯一可接受的值。

Availability: Unix.

3.3 新版功能.

time.clocksettime_ns(_clk_id, time: int)
与 clock_settime() 相似，但设置时间为纳秒。

Availability: Unix.

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.getclock_info(_name)
获取有关指定时钟的信息作为命名空间对象。支持的时钟名称和读取其值的相应函数是：
- 'clock': time.clock()
- '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])
将 seconds since the epoch 为单位的时间转换为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 的时间，而不是 UTC 。它返回一个浮点数，以便与 time() 兼容。如果输入值不能表示为有效时间，则 OverflowError 或 ValueError 将被引发（这取决于Python或底层C库是否捕获到无效值）。它可以生成时间的最早日期取决于平台。
time.monotonic() → float
返回单调时钟的值（以小数秒为单位），即不能倒退的时钟。时钟不受系统时钟更新的影响。返回值的参考点未定义，因此只有连续调用结果之间的差异才有效。

3.3 新版功能.

在 3.5 版更改: 该功能现在始终可用且始终在系统范围内。

time.monotonic_ns() → int
与 monotonic() 相似，但是返回时间为纳秒数。

3.7 新版功能.

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

3.3 新版功能.

time.perf_counter_ns() → int
与 perf_counter() 相似，但是返回时间为纳秒。

3.7 新版功能.

time.process_time() → float
返回当前进程的系统和用户CPU时间总和的值（以小数秒为单位）。它不包括睡眠期间经过的时间。根据定义，它在整个进程范围中。返回值的参考点未定义，因此只有连续调用结果之间的差异才有效。

3.3 新版功能.

time.process_time_ns() → int
与 process_time() 相似，但是返回时间为纳秒。

3.7 新版功能.

time.sleep(secs)
暂停执行调用线程达到给定的秒数。参数可以是浮点数，以指示更精确的睡眠时间。实际的暂停时间可能小于请求的时间，因为任何捕获的信号将在执行该信号的捕获例程后终止 sleep() 。此外，由于系统中其他活动的安排，暂停时间可能比请求的时间长任意量。

在 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] 。

%Z

时区名称（如果不存在时区，则不包含字符）。

%%

字面的 '%' 字符。

注释:

当与 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")   # doctest: +NORMALIZE_WHITESPACE
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 接口的对象：可以通过索引和属性名访问值。存在以下值：

索引

属性

值

tm_year

（例如，1993）

tm_mon

range [1, 12]

tm_mday

range [1, 31]

tm_hour

range [0, 23]

tm_min

range [0, 59]

tm_sec

range [0, 61]；见 strftime() 介绍中的 (2)

tm_wday

range [0, 6] ，周一为 0

tm_yday

range [1, 366]

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
返回浮点数的 seconds since the epoch 。epoch 的具体日期和 leap seconds 的处理取决于平台。在Windows和大多数Unix系统上， epoch 是1970年1月1日00:00:00（UTC），并且闰秒不计入 seconds since the epoch 。这通常被称为 Unix time 。要找出给定平台上的 epoch ，请查看 gmtime(0) 。

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

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

time.thread_time() → float
返回当前线程的系统和用户CPU时间之和的值（以小数秒为单位）。它不包括睡眠期间经过的时间。根据定义，它是特定于线程的。返回值的参考点未定义，因此只有同一线程中连续调用结果之间的差异才有效。

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

3.7 新版功能.

time.thread_time_ns() → int
与 thread_time() 相似，但返回纳秒时间。

3.7 新版功能.

time.time_ns() → int
与 time() 相似，但返回时间为用整数表示的自 epoch 以来所经过的纳秒数。

3.7 新版功能.

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

Availability: Unix.

注解

虽然在很多情况下，更改 TZ 环境变量而不调用 tzset() 可能会影响函数的输出，例如 localtime() ，不应该依赖此行为。

TZ 不应该包含空格。

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返回。开始日期和结束日期的格式为以下之一：
- 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 天发生的第一周。第 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
无法设置的时钟，表示自某些未指定的起点以来的单调时间。

Availability: 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的高分辨率每进程计时器。

Availability: Unix.

3.3 新版功能.

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

可用性: FreeBSD， NetBSD 7 或更新， OpenBSD.

3.7 新版功能.

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

Availability: Unix.

3.3 新版功能.

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

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

3.7 新版功能.

time.CLOCK_UPTIME_RAW
单调递增的时钟，记录从一个任意起点开始的时间，不受频率或时间调整的影响，并且当系统休眠时将不会递增。

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

3.8 新版功能.

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

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

Availability: Unix.

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 来获取时区信息。

参见

模块 datetime
更多面向对象的日期和时间接口。
模块 locale
国际化服务。区域设置会影响 strftime() 和 strptime() 中许多格式说明符的解析。
模块 calendar
一般日历相关功能。这个模块的 timegm() 是函数 gmtime() 的反函数。

脚注

1
现在不推荐使用 %Z ，但是所有 ANSI C 库都不支持扩展为首选小时/分钟偏移量的%z转义符。此外，严格的 1982 年原始 RFC 822 标准要求两位数的年份（%y而不是%Y），但是实际在2000年之前很久就转移到了4位数年。之后， RFC 822 已经废弃了，4位数的年份首先被推荐 RFC 1123 ，然后被 RFC 2822 强制执行。