time — 时间访问和转换 — Python 文档
time — 时间访问和转换
该模块提供各种与时间相关的功能。 有关相关功能,另请参阅 datetime 和 calendar 模块。
尽管此模块始终可用,但并非所有功能都适用于所有平台。 该模块中定义的大部分函数调用同名的平台 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() 将接受具有非零分数的时间(Unixselect()
用于实现这,在可用的情况下)。gmtime()、localtime()和strptime()返回的时间值,并被asctime()接受, mktime() 和 strftime() 是 9 个整数的序列。 gmtime()、localtime() 和 strptime() 的返回值还提供了各个字段的属性名称。
有关这些对象的描述,请参阅 struct_time。
3.3 版本更改: struct_time 类型扩展为当平台支持相应的
struct tm
成员时提供tm_gmtoff
和tm_zone
属性.3.6 版更改: struct_time 属性
tm_gmtoff
和tm_zone
现在在所有平台上可用。使用以下函数在时间表示之间进行转换:
从
到
采用
自纪元以来的秒数
struct_time UTC
自纪元以来的秒数
struct_time 当地时间
struct_time UTC
自纪元以来的秒数
struct_time 当地时间
自纪元以来的秒数
功能
- 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_ns(clk_id) int
类似于 clock_gettime() 但返回时间为纳秒。
3.7 版中的新功能。
- time.clock_settime(clk_id, time: float)
设置指定时钟的时间clk_id。 目前,CLOCK_REALTIME 是 clk_id 唯一可接受的值。
3.3 版中的新功能。
- time.clock_settime_ns(clk_id, time: int)
类似于 clock_settime() 但以纳秒设置时间。
3.7 版中的新功能。
- time.ctime([secs])
- 将自纪元以来以秒表示的时间转换为表示本地时间的字符串。 如果未提供 secs 或 None,则使用 time() 返回的当前时间。
ctime(secs)
相当于asctime(localtime(secs))
。 ctime() 不使用区域设置信息。
- time.get_clock_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:
True
如果时钟可以自动改变(例如 由 NTP 守护进程)或由系统管理员手动,False
否则implementation:用于获取时钟值的底层C函数的名称。 有关可能的值,请参阅 时钟 ID 常数 。
monotonic:
True
如果时钟不能倒退,False
否则resolution:以秒为单位的时钟分辨率(float)
3.3 版中的新功能。
- time.gmtime([secs])
- 将自纪元以来以秒表示的时间转换为 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[ X173X] 时间,而不是 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 版更改: 即使睡眠被信号中断,该函数现在至少睡眠 秒 ,除非信号处理程序引发异常(请参阅 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
时区名称(如果不存在时区,则无字符)。
%%
文字
'%'
字符。笔记:
当与 strptime() 函数一起使用时,如果
%I
指令用于解析小时,则%p
指令仅影响输出小时字段。范围实际上是
0
到61
; 值60
在表示 闰秒 的时间戳中有效,并且由于历史原因支持值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() 使用的指令相同; 它默认为
"%a %b %d %H:%M:%S %Y"
,它与 ctime() 返回的格式匹配。 如果string无法按照格式解析,或者解析后有多余数据,则抛出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()返回的时间值序列的类型。 它是一个具有 命名元组 接口的对象:可以通过索引和属性名称访问值。 存在以下值:
指数
属性
价值观
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.tzset()
重置库例程使用的时间转换规则。 环境变量
TZ
指定这是如何完成的。 它还将设置变量tzname
(来自TZ
环境变量)、timezone
(UTC 以西的非 DST 秒)、altzone
(UTC 以西的 DST 秒)和daylight
(如果此时区没有任何夏令时规则,则为 0,如果有夏令时的过去、现在或将来的时间,则为非零值适用)。TZ
环境变量的标准格式是(为了清晰起见添加了空格):std offset [dst [offset [,start[/time], end[/time]]]]
组件在哪里:
std
和dst
给出时区缩写的三个或更多字母数字。 这些将被传播到 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天发生的第一周。 零日是星期日。
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()
或类似方法更改时间,则可能会出现不连续性。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 时区,则不应使用第二个字符串。 请参阅下面的注释。
笔记
对于上述时区常量(altzone、daylight、timezone和tzname),其值由生效的时区规则决定在模块加载时或最后一次 tzset() 被调用时,过去可能不正确。 建议使用localtime()的tm_gmtoff
和tm_zone
结果来获取时区信息。
也可以看看
- 模块日期时间
- 更多面向对象的日期和时间接口。
- 模块 语言环境
- 国际化服务。 区域设置会影响 strftime() 和 strptime() 中许多格式说明符的解释。
- 模块 日历
- 通用日历相关功能。 timegm() 是来自该模块的 gmtime() 的倒数。
脚注
- 1
- 现在不推荐使用
%Z
,但所有 ANSI C 库都不支持扩展到首选小时/分钟偏移量的%z
转义。 此外,严格阅读原始的 1982 RFC 822 标准要求使用两位数的年份(%y 而不是 %Y),但实践在很久以前就转移到了 4 位数的年份2000 年。 在那之后,RFC 822 变得过时,4 位数字的年份首先由 RFC 1123 推荐,然后由 强制规定]RFC 2822。