时间-时间访问和转化

---

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

尽管此模块始终可用，但并非所有Function在所有平台上都可用。该模块中定义的大多数函数都调用具有相同名称的平台 C 库函数。有时查阅平台文档可能会有所帮助，因为这些Function的语义在平台之间会有所不同。

必须对一些术语和约定进行解释。

• • epoch *是时间开始的时间点，与平台有关。对于 Unix，纪元是 1970 年 1 月 1 日，00：00：00(UTC)。要了解给定平台上的纪元，请查看time.gmtime(0)。

• 术语“自纪元以来的秒数”是指自纪元以来经过的秒数总数，通常不包括leap seconds。在所有符合 POSIX 的平台上，seconds 秒不包括在此总数之内。

• 该模块中的Function可能无法处理时间点之前或将来的日期和时间。Future 的临界点由 C 库确定；对于 32 位系统，通常在 2038 年。

• 给定%y格式代码后，函数strptime()可以解析两位数的年份。解析了两位数的年份后，将根据 POSIX 和 ISO C 标准进行转换：将值 69-99Map 到 1969-1999，将值 0-68Map 到 2000-2068.

• UTC 是协调世界时(以前称为 Greenwich 标准时间，即 GMT)。 UTC 的缩写不是一个错误，而是英语和法语之间的折衷。

• DST 是夏令时，在一年中的部分时间(通常)将时区调整为一小时。 DST 规则是不可思议的(由当地法律决定)，并且可以每年更改。 C 库有一个包含本地规则的表(通常出于灵 Active 考虑，它是从系统文件中读取的)，并且在这方面是 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 tm成员时，struct_time类型已扩展为提供tm_gmtoff和tm_zone属性。

在版本 3.6 中进行了更改：struct_time属性tm_gmtoff和tm_zone现在在所有平台上都可用。

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

Functions

• time. asctime([* t *])
  • 将表示gmtime()或localtime()返回的时间的 Tuples 或struct_time转换为以下形式的字符串：'Sun Jun 20 23:21:05 1993'。日字段长为两个字符，如果日是一位数字(例如'Wed Jun 9 04:26:40 1993')，则用空格填充。

如果未提供* t *，则使用localtime()返回的当前时间。 asctime()不使用语言环境信息。

• time. pthread_getcpuclockid(* thread_id *)
  • 返回指定的* thread_id 的线程特定的 CPU 时间时钟的 clk_id *。

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

Availability：Unix(有关更多信息，请参见手册页上的pthread_getcpuclockid(3) *)。

3.7 版中的新Function。

• time. clock_getres(* clk_id *)
  • 返回指定时钟* clk_id 的分辨率(精度)。请参阅时钟 ID 常数以获取 clk_id *的可接受值列表。

Availability: Unix.

版本 3.3 中的新Function。

• time. clock_gettime(* clk_id *)→浮点
  • 返回指定时钟* clk_id 的时间。请参阅时钟 ID 常数以获取 clk_id *的可接受值列表。

Availability: Unix.

版本 3.3 中的新Function。

• time. clock_gettime_ns(* clk_id *)→整数
  • 与clock_gettime()类似，但返回时间为纳秒。

Availability: Unix.

3.7 版中的新Function。

• time. clock_settime(* clk_id ， time：float *)
  • 设置指定时钟* clk_id 的时间。当前，CLOCK_REALTIME是 clk_id *唯一接受的值。

Availability: Unix.

版本 3.3 中的新Function。

• time. clock_settime_ns(* clk_id ， time：int *)
  • 与clock_settime()类似，但是将时间设置为纳秒。

Availability: Unix.

3.7 版中的新Function。

• time. ctime([秒])
  • 将自纪元以来的时间(秒)转换为以下形式的字符串：'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 *)

  • 获取有关指定时钟的信息作为名称空间对象。支持的时钟名称和读取其值的相应Function是：

• 'monotonic' : time.monotonic()

• 'perf_counter' : time.perf_counter()

• 'process_time' : time.process_time()

• 'thread_time' : time.thread_time()

• 'time' : time.time()

结果具有以下属性：

• • adjustable *：True(如果时钟可以自动更改(例如pass NTP 守护程序)或由系统 Management 员手动更改，否则False)
• • implementation *：用于获取时钟值的基础 C 函数的名称。请参阅时钟 ID 常数以获取可能的值。

• 单调：True(如果时钟无法倒退，否则False)

• • resolution *：时钟的分辨率，以秒为单位(float)

版本 3.3 中的新Function。

• time. gmtime([秒])

  • 将自纪元以来的时间(秒)转换为 UTC 中的struct_time，其中 dst 标志始终为零。如果未提供* secs *或None，则使用time()返回的当前时间。小数秒被忽略。有关struct_time对象的说明，请参见上文。有关此函数的反函数，请参见calendar.timegm()。

• time. localtime([秒])

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

• time. mktime(* t *)

  • 这是localtime()的反函数。它的参数是struct_time或完整的 9Tuples(因为需要 dst 标志；如果未知，请使用-1作为 dst 标志)，它以* local *时间而不是 UTC 表示时间。返回一个浮点数，以与time()兼容。如果 Importing 值不能表示为有效时间，则将引发OverflowError或ValueError(取决于无效值是被 Python 还是底层 C 库捕获)。它可以生成时间的最早日期取决于平台。

• time. monotonic()→Float

  • 返回单调时钟的值(以秒为单位)，即不能向后移动的时钟。该时钟不受系统时钟更新的影响。返回值的参考点是不确定的，因此仅连续调用结果之间的差有效。

版本 3.3 中的新Function。

在版本 3.5 中更改：该Function现在始终可用，并且始终在系统范围内。

• time. monotonic_ns()→整数
  • 与monotonic()相似，但返回时间以纳秒为单位。

3.7 版中的新Function。

• time. perf_counter()→Float
  • 返回性能计数器的值(以分数秒为单位)，即具有最高可用分辨率的时钟以测量短时间。它确实包括整个系统的睡眠时间。返回值的参考点是不确定的，因此仅连续调用结果之间的差有效。

版本 3.3 中的新Function。

• time. perf_counter_ns()→整数
  • 与perf_counter()相似，但返回时间以纳秒为单位。

3.7 版中的新Function。

• time. process_time()→Float
  • 返回当前进程的系统和用户 CPU 时间之和的值(以秒为单位)。它不包括睡眠期间经过的时间。根据定义，它是整个过程的。返回值的参考点是不确定的，因此仅连续调用结果之间的差有效。

版本 3.3 中的新Function。

• time. process_time_ns()→整数
  • 与process_time()类似，但返回时间为纳秒。

3.7 版中的新Function。

• time. sleep(秒)
  • 在给定的秒数内暂停调用线程的执行。该参数可以是浮点数，以指示更精确的睡眠时间。实际的暂停时间可能少于请求的暂停时间，因为任何捕获到的 signal 都会在执行该 signal 的捕获例程后终止sleep()。而且，由于系统中其他活动的调度，暂停时间可能比请求的时间长任意数量。

在版本 3.5 中进行了更改：现在，即使睡眠被 signal break，该函数也将至少睡眠* secs *，除非 signal 处理程序引发异常(有关原理，请参见 PEP 475)。

• time. strftime(* format * [，* t *])
  • 将表示gmtime()或localtime()返回的时间的 Tuples 或struct_time转换为* format 参数指定的字符串。如果未提供 t ，则使用localtime()返回的当前时间。 格式必须为字符串。如果 t *中的任何字段超出允许范围，则引发ValueError。

0 是时间 Tuples 中任何位置的合法论点；如果通常是非法的，则将该值强制为正确的值。

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

Notes:

• 与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) *文档。

在某些平台上，可选的字段宽度和精度规范可以按以下 Sequences 立即位于指令的初始'%'后面；这也不是便携式的。字段宽度通常为 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 *都必须是字符串。

For example:

>>> 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()独立于任何平台，因此不一定支持未记录为受支持的所有可用指令。

• 类别 time. struct_time
  • gmtime()，localtime()和strptime()返回的时间值序列的类型。它是带有named tuple接口的对象：可以pass索引和属性名称访问值。存在以下值：

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

在对mktime()的呼叫中，如果实行夏令时，则tm_isdst可以设置为 1，否则不设置为 0.值-1 表示这是未知的，通常会导致填写正确的状态。

将长度不正确的 Tuples 传递给期望struct_time或具有错误类型的元素的函数时，将引发TypeError。

• time. time()→Float
  • 以epoch作为浮点数返回以秒为单位的时间。纪元的具体日期和leap seconds的处理方式取决于平台。在 Windows 和大多数 Unix 系统上，纪元是 1970 年 1 月 1 日，00：00：00(UTC)，leap 秒不计入自纪元以来的秒数。这通常称为Unix time。要找出给定平台上的纪元，请查看gmtime(0)。

请注意，即使时间总是以浮点数形式返回，但并非所有系统都提供比 1 秒更好的精度的时间。尽管此函数通常返回非递减值，但如果两次调用之间的系统时钟都已设置为零，则它可以返回比上一个调用更低的值。

pass将time()返回的数字传递给gmtime()函数，可以将其转换为更通用的时间格式(即年，月，日，小时等)，以 UTC 表示，或者pass将其传递给localtime()函数，以本地时间转换为更常用的时间格式。在这两种情况下，都将返回一个struct_time对象，可以从中访问 calendar 日期的组成部分作为属性。

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

Availability：支持CLOCK_THREAD_CPUTIME_ID的 Windows，Linux，Unix 系统。

3.7 版中的新Function。

• time. thread_time_ns()→整数
  • 与thread_time()类似，但返回时间为纳秒。

3.7 版中的新Function。

• time. time_ns()→整数
  • 与time()相似，但返回的时间是自epoch以来的整数纳秒。

3.7 版中的新Function。

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

Availability: 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 返回。开始日期和结束日期的格式为以下之一：

• Jn

   - The Julian day  *n*  \(1 \<=  *n*  \<= 365\)\. Leap days are not counted, so in all years February 28 is day 59 and March 1 is day 60\.
  

  • n

    • 从零开始的儒略日(0 <= * n * <= 365)。日被计算在内，可以参考 2 月 29 日。

  • Mm.n.d

    • 月份的第* d 日(0 <= * d * <= 6) n 月的第 m 年(1 <= * n * <= 5，1 <= * m * <= 12，其中第 5 周表示“月份中的最后 d 天 m ”，可能在第四周或第五周出现。第 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相同，除了它还包括系统挂起的任何时间。

这允许应用程序获得可感知暂停的单调时钟，而不必处理CLOCK_REALTIME的复杂性，如果使用settimeofday()或类似时间更改时间，则可能会出现break。

Availability：Linux 2.6.39 或更高版本。

3.7 版中的新Function。

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

Availability: Solaris.

版本 3.3 中的新Function。

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

Availability: Unix.

版本 3.3 中的新Function。

• time. CLOCK_MONOTONIC_RAW
  • 与CLOCK_MONOTONIC相似，但是可以访问不受 NTP 调整的基于硬件的原始时间。

Availability：Linux 2.6.28 和更高版本，macOS 10.12 和更高版本。

版本 3.3 中的新Function。

• time. CLOCK_PROCESS_CPUTIME_ID
  • CPU 的高分辨率每个进程计时器。

Availability: Unix.

版本 3.3 中的新Function。

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

Availability：FreeBSD，NetBSD 7 或更高版本，OpenBSD。

3.7 版中的新Function。

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

Availability: Unix.

版本 3.3 中的新Function。

• time. CLOCK_UPTIME
  • 时间，其绝对值是系统已运行且未挂起的时间，可提供准确的运行时间测量，包括绝对时间和间隔时间。

Availability：FreeBSD，OpenBSD 5.5 或更高版本。

3.7 版中的新Function。

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

Availability：macOS 10.12 及更高版本。

3.8 版的新Function。

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

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

Availability: Unix.

版本 3.3 中的新Function。

Timezone Constants

• time. altzone

  • 如果已定义，则本地 DST 时区的偏移量(以 UTC 以西为秒)。如果当地 DST 时区位于 UTC 东部(如西欧，包括英国)，则为负。仅当daylight不为零时才使用。请参阅下面的 Comments。

• time. daylight

  • 如果定义了 DST 时区，则为非零值。请参阅下面的 Comments。

• time. timezone

  • 本地(非 DST)时区的偏移量，以 UTC 以西为秒(西欧大部分 locale 为负，美国为正，英国为零)。请参阅下面的 Comments。

• time. tzname

  • 由两个字符串组成的 Tuples：第一个是本地非 DST 时区的名称，第二个是本地 DST 时区的名称。如果未定义 DST 时区，则不应使用第二个字符串。请参阅下面的 Comments。

Footnotes

• [1]
  • 现在已不建议使用%Z，但是并非所有 ANSI C 库都支持将%z转义扩展为首选的小时/分钟偏移量。同样，严格阅读原始 1982 RFC 822标准要求使用两位数的年份(％y 而不是％Y)，但是实践已移至 2000 年之前的 4 位年份。在那之后， RFC 822变得过时了， 4 位年份首先由 RFC 1123建议，然后由 RFC 2822规定。