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

来自菜鸟教程
Python/docs/3.7/library/time
跳转至:导航、​搜索

time — 时间访问和转换


该模块提供各种与时间相关的功能。 有关相关功能,另请参阅 datetimecalendar 模块。

尽管此模块始终可用,但并非所有功能都适用于所有平台。 该模块中定义的大部分函数调用同名的平台 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_gmtofftm_zone 属性.

    3.6 版更改: struct_time 属性 tm_gmtofftm_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' . 如果未提供 t,则使用 localtime() 返回的当前时间。 asctime() 不使用区域设置信息。

笔记

与同名的 C 函数不同,asctime() 不添加尾随换行符。

time.clock()

在 Unix 上,将当前处理器时间返回为以秒表示的浮点数。 精度,实际上是“处理器时间”含义的定义,取决于同名 C 函数的精度。

在 Windows 上,此函数根据 Win32 函数 QueryPerformanceCounter(),以浮点数形式返回自第一次调用此函数以来经过的挂钟秒数。 分辨率通常优于一微秒。

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 常量

3.3 版中的新功能。

time.clock_gettime_ns(clk_id) int

类似于 clock_gettime() 但返回时间为纳秒。

3.7 版中的新功能。

time.clock_settime(clk_id, time: float)

设置指定时钟的时间clk_id。 目前,CLOCK_REALTIMEclk_id 唯一可接受的值。

3.3 版中的新功能。

time.clock_settime_ns(clk_id, time: int)

类似于 clock_settime() 但以纳秒设置时间。

3.7 版中的新功能。

time.ctime([secs])
将自纪元以来以秒表示的时间转换为表示本地时间的字符串。 如果未提供 secsNone,则使用 time() 返回的当前时间。 ctime(secs) 相当于 asctime(localtime(secs))ctime() 不使用区域设置信息。
time.get_clock_info(name)

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

结果具有以下属性:

  • adjustable: True 如果时钟可以自动改变(例如 由 NTP 守护进程)或由系统管理员手动,False 否则

  • implementation:用于获取时钟值的底层C函数的名称。 有关可能的值,请参阅 时钟 ID 常数

  • monotonicTrue如果时钟不能倒退,False否则

  • resolution:以秒为单位的时钟分辨率(float

3.3 版中的新功能。

time.gmtime([secs])
将自纪元以来以秒表示的时间转换为 UTC 中的 struct_time,其中 dst 标志始终为零。 如果未提供 secsNone,则使用 time() 返回的当前时间。 一秒的分数被忽略。 有关 struct_time 对象的描述,请参见上文。 请参阅 calendar.timegm() 了解此函数的反函数。
time.localtime([secs])
gmtime() 但转换为本地时间。 如果未提供 secsNone,则使用 time() 返回的当前时间。 当 DST 适用于给定时间时,dst 标志设置为 1
time.mktime(t)
这是 localtime() 的反函数。 它的参数是 struct_time 或完整的 9 元组(因为需要 dst 标志;如果未知,则使用 -1 作为 dst 标志)表示 local[ X173X] 时间,而不是 UTC。 它返回一个浮点数,以与 time() 兼容。 如果输入值不能表示为有效时间,则会引发 OverflowErrorValueError(这取决于无效值是被 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 版更改: 即使睡眠被信号中断,该函数现在至少睡眠 ,除非信号处理程序引发异常(请参阅 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

时区名称(如果不存在时区,则无字符)。

%%

文字 '%' 字符。

笔记:

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

  2. 范围实际上是 061; 值 60 在表示 闰秒 的时间戳中有效,并且由于历史原因支持值 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() 使用的指令相同; 它默认为 "%a %b %d %H:%M:%S %Y",它与 ctime() 返回的格式匹配。 如果string无法按照格式解析,或者解析后有多余数据,则抛出ValueError。 当无法推断出更准确的值时,用于填充任何缺失数据的默认值为 (1900, 1, 1, 0, 0, 0, 0, 1, -1)stringformat 都必须是字符串。

例如:

>>> 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.thread_time() float

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

3.7 版中的新功能。

time.thread_time_ns() int

类似于 thread_time() 但返回时间为纳秒。

3.7 版中的新功能。

time.time_ns() int

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

组件在哪里:

stddst

给出时区缩写的三个或更多字母数字。 这些将被传播到 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天发生的第一周。 零日是星期日。

timeoffset 的格式相同,但不允许使用前导符号('-' 或 '+')。 如果未给出时间,则默认值为 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() 或类似方法更改时间,则可能会出现不连续性。

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_THREAD_CPUTIME_ID

线程特定的 CPU 时间时钟。

3.3 版中的新功能。

time.CLOCK_UPTIME

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

3.7 版中的新功能。

以下常量是唯一可以发送到 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 时区,则不应使用第二个字符串。 请参阅下面的注释。

笔记

对于上述时区常量(altzonedaylighttimezonetzname),其值由生效的时区规则决定在模块加载时或最后一次 tzset() 被调用时,过去可能不正确。 建议使用localtime()tm_gmtofftm_zone结果来获取时区信息。


也可以看看

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


脚注

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