time —- 时间的访问和转换

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

尽管所有平台皆可使用此模块，但模块内的函数并非所有平台都可用。此模块中定义的大多数函数的实现都是调用其所在平台的C语言库的同名函数。因为这些函数的语义可能因平台而异，所以使用时最好查阅对应平台的相关文档。

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

• The epoch is the point where the time starts, the return value of time.gmtime(0). It is January 1, 1970, 00:00:00 (UTC) on all platforms.

• 术语 纪元秒数 是指自 epoch （纪元）时间点以来经过的总秒数，通常不包括 闰秒。 在所有符合 POSIX 标准的平台上，闰秒都不会记录在总秒数中。

• The functions in this module may not handle dates and times before the epoch or far in the future. The cut-off point in the future is determined by the C library; for 32-bit systems, it is typically in 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() 返回最准确的时间 （使用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.pthread_getcpuclockid(thread_id)

返回指定的 thread_id 的特定于线程的CPU时间时钟的 clk_id 。

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

警告

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

Availability: Unix

See the man page for pthread_getcpuclockid(3)) for further information.

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])

Convert a time expressed in seconds since the epoch to a string of a form: 'Sun Jun 20 23:21:05 1993' representing local time. The day field is two characters long and is space padded if the day is a single digit, e.g.: '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])

Convert a time expressed in seconds since the epoch to a struct_time in UTC in which the dst flag is always zero. If secs is not provided or None, the current time as returned by time() is used. Fractions of a second are ignored. See above for a description of the struct_time object. See calendar.timegm() for the inverse of this function.

time.localtime([secs])

与 gmtime() 相似但转换为当地时间。如果未提供 secs 或为 None ，则使用由 time() 返回的当前时间。当 DST 适用于给定时间时，dst标志设置为 1 。

localtime() 可能会引发 OverflowError ，如果时间戳超出平台 C localtime() 或 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)

Suspend execution of the calling thread for the given number of seconds. The argument may be a floating point number to indicate a more precise sleep time.

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.

The suspension time may be longer than requested by an arbitrary amount, because of the scheduling of other activity in the system.

On Windows, if secs is zero, the thread relinquishes the remainder of its time slice to any other thread that is ready to run. If there are no other threads ready to run, the function returns immediately, and the thread continues execution. On Windows 8.1 and newer the implementation uses a high-resolution timer which provides resolution of 100 nanoseconds. If secs is zero, Sleep(0) is used.

Unix implementation:

• Use clock_nanosleep() if available (resolution: 1 nanosecond);

• Or use nanosleep() if available (resolution: 1 nanosecond);

• Or use select() (resolution: 1 microsecond).

在 3.11 版更改: On Unix, the clock_nanosleep() and nanosleep() functions are now used if available. On Windows, a waitable timer is now used.

在 3.5 版更改: 现在，即使该睡眠过程被信号中断，该函数也会保证调用它的线程至少会睡眠 secs 秒。信号处理例程抛出异常的情况除外。（欲了解我们做出这次改变的原因，请参见 PEP 475 ）

time.strftime(format[, t])

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

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

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

注释：

1. 当与 strptime() 函数一起使用时，如果使用 %I 指令来解析小时， %p 指令只影响输出小时字段。

2. 范围真的是 0 到 61 ；值 60 在表示 leap seconds 的时间戳中有效，并且由于历史原因支持值 61 。

3. 当与 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 接口的对象：可以通过索引和属性名访问值。 存在以下值：

请注意，与C结构不同，月份值是 [1,12] 的范围，而不是 [0,11] 。

在调用 mktime() 时， tm_isdst 可以在夏令时生效时设置为1，而在夏令时不生效时设置为0。 值-1表示这是未知的，并且通常会导致填写正确的状态。

当一个长度不正确的元组被传递给期望 struct_time 的函数，或者具有错误类型的元素时，会引发 TypeError 。

time.time() → float

Return the time in seconds since the epoch as a floating point number. The handling of leap seconds is platform dependent. On Windows and most Unix systems, the leap seconds are not counted towards the time in seconds since the epoch. This is commonly referred to as Unix time.

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

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

使用 time_ns() 以避免 float 类型导致的精度损失。

time.time_ns() → int

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

3.7 新版功能.

time.thread_time() → float

（以小数表示的秒为单位）返回当前线程的系统和用户 CPU 时间的总计值。 它不包括睡眠状态所消耗的时间。 根据定义它只作用于线程范围。 返回值的参考点未被定义，因此只有两次调用之间的差值才是有效的。

使用 thread_time_ns() 以避免 float 类型导致的精度损失。

Availability: Linux, Unix, Windows.

Unix systems supporting CLOCK_THREAD_CPUTIME_ID.

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 环境变量而不调用 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返回。开始日期和结束日期的格式为以下之一：

  • J*n*

    Julian日 n （1 <= n <= 365）。闰日不计算在内，因此在所有年份中，2月28日是第59天，3月1日是第60天。

    *n*

    从零开始的Julian日（0 <= n <= 365）。 闰日计入，可以引用2月29日。

    M*m*.*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() 或类似的时间更改时间可能会有不连续性。

Availability: Linux >= 2.6.39.

3.7 新版功能.

time.CLOCK_HIGHRES

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

可用性: Solaris.

3.3 新版功能.

time.CLOCK_MONOTONIC

无法设置的时钟，表示自某些未指定的起点以来的单调时间。

可用性: Unix。

3.3 新版功能.

time.CLOCK_MONOTONIC_RAW

类似于 CLOCK_MONOTONIC ，但可以访问不受NTP调整影响的原始硬件时间。

Availability: Linux >= 2.6.28, macOS >= 10.12.

3.3 新版功能.

time.CLOCK_PROCESS_CPUTIME_ID

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

可用性: Unix。

3.3 新版功能.

time.CLOCK_PROF

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

Availability: FreeBSD, NetBSD >= 7, OpenBSD.

3.7 新版功能.

time.CLOCK_TAI

国际原子时间

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

可用性: Linux。

3.9 新版功能.

time.CLOCK_THREAD_CPUTIME_ID

特定于线程的CPU时钟。

可用性: Unix。

3.3 新版功能.

time.CLOCK_UPTIME

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

Availability: FreeBSD, OpenBSD >= 5.5.

3.7 新版功能.

time.CLOCK_UPTIME_RAW

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

Availability: macOS >= 10.12.

3.8 新版功能.

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

time.CLOCK_REALTIME

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

可用性: 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(1,2,3)

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