Skip to main content

16.3. time —时间访问和转换


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

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

一些术语和约定的解释是有序的。

  • epoch 是时间开始的点。在那一年的1月1日,在0小时,“自时代以来的时间”为零。对于Unix,时代是1970年。要找出什么是时代,看看 gmtime(0)

  • 此模块中的函数可能无法处理时代之前或未来的日期和时间。未来的截止点由C库决定;对于32位系统,它通常在2038年。

  • 2000年(Y2K)问题:Python依赖于平台的C库,它通常不会有2000年问题,因为所有的日期和时间都在内部表示为自从时代的秒。功能 strptime() 可以在给定 %y 格式代码时解析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 tm 成员时,struct_time 类型被扩展以提供 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.altzone

本地DST时区的偏移量,以UTC为单位的秒数(如果定义了一个)。如果本地DST时区在UTC的东部(如在西欧,包括英国),则为负。只有在 daylight 非零时才使用。

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() 返回从第一次调用此函数起经过的挂钟秒数作为浮点数。分辨率通常优于一微秒。

3.3 版后已移除: 此功能的行为取决于平台:根据您的要求,使用 perf_counter()process_time(),以具有良好定义的行为。

time.clock_getres(clk_id)

返回指定时钟 clk_id 的分辨率(精度)。

可用性:Unix。

3.3 新版功能.

time.clock_gettime(clk_id)

返回指定时钟 clk_id 的时间。

可用性:Unix。

3.3 新版功能.

time.clock_settime(clk_id, time)

设置指定时钟 clk_id 的时间。

可用性:Unix。

3.3 新版功能.

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调整的基于硬件的原始时间的访问。

可用性:Linux 2.6.28或更高版本。

3.3 新版功能.

time.CLOCK_PROCESS_CPUTIME_ID

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

可用性:Unix。

3.3 新版功能.

time.CLOCK_REALTIME

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

可用性:Unix。

3.3 新版功能.

time.CLOCK_THREAD_CPUTIME_ID

线程特定的CPU时钟。

可用性:Unix。

3.3 新版功能.

time.ctime([secs])

将从纪元开始以秒表示的时间转换为表示本地时间的字符串。如果未提供 secsNone,则使用 time() 返回的当前时间。 ctime(secs) 等价于 asctime(localtime(secs))ctime() 不使用区域设置信息。

time.daylight

如果定义了DST时区,则为非零。

time.get_clock_info(name)

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

结果具有以下属性:

  • adjustableTrue 如果时钟可以自动更改(例如通过NTP守护程序)或由系统管理员手动更改,False

  • implementation:用于获取时钟值的基本C函数的名称

  • 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 时间而不是UTC的时间。它返回一个浮点数,以与 time() 兼容。如果输入值不能表示为有效时间,则将引发 OverflowErrorValueError (这取决于无效值是由Python还是由底层C库捕获)。它可以生成时间的最早日期是平台相关的。

time.monotonic()

返回单调时钟的值(以秒为单位),即不能倒退的时钟。时钟不受系统时钟更新的影响。返回值的参考点未定义,因此只有连续调用结果之间的差异有效。

在Vista以上的Windows版本上,monotonic() 检测到 GetTickCount() 整数溢出(32位,在49.7天后翻转)。每次检测到溢出时,它将内部时间(参考时间)增加2 32。该时期存储在进程本地状态中,因此 monotonic() 的值可能在运行超过49天的两个Python进程中不同。在更新版本的Windows和其他操作系统上,monotonic() 是系统级的。

3.3 新版功能.

在 3.5 版更改: 该功能现在总是可用。

time.perf_counter()

返回性能计数器的值(以分秒为单位),即具有最高可用分辨率的时钟,以测量短持续时间。它包括在睡眠期间和系统范围内流逝的时间。返回值的参考点未定义,因此只有连续调用结果之间的差异有效。

3.3 新版功能.

time.process_time()

返回当前进程的系统和用户CPU时间之和的值(以分数秒为单位)。它不包括睡眠期间经过的时间。它是整个过程的定义。返回值的参考点未定义,因此只有连续调用结果之间的差异有效。

3.3 新版功能.

time.sleep(secs)

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

在 3.5 版更改: 该函数现在至少睡眠 secs,即使睡眠被信号中断,除非信号处理程序引发异常(参见 PEP 475 的理由)。

time.strftime(format[, t])

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

0是时间元组中任何位置的法律参数;如果通常是非法的,则该值被强制为正确的值。

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

指示

含义

笔记

%a

Locale的缩写工作日名称。

 

%A

Locale的整个工作日名称。

 

%b

语言环境的缩写月份名称。

 

%B

Locale的完整月份名称。

 

%c

语言环境的适当日期和时间表示。

 

%d

一个十进制数字[01,31]。

 

%H

小时(24小时制)为十进制数[00,23]。

 

%I

小时(12小时制)十进制数[01,12]。

 

%j

一年中的十进制数[001,366]。

 

%m

月为十进制数[01,12]。

 

%M

分钟为十进制数[00,59]。

 

%p

Locale相当于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

时区偏移,指示与+ 或- 格式的UTC/GMT的正或负时差,其中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 不能根据 format 被解析,或者如果它在解析之后具有过多的数据,则 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() 返回的时间值序列的类型。它是一个具有 named tuple 接口的对象:可以通过索引和属性名访问值。存在以下值:

指数

属性

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

range [0,61];见 strftime() 描述中的 (2)

6

tm_wday

范围[0,6],星期一为0

7

tm_yday

范围[1,366]

8

tm_isdst

0,1或-1;见下文

N/A

tm_zone

时区名称的缩写

N/A

tm_gmtoff

在UTC的东部偏移,以秒为单位

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

在对 mktime() 的调用中,当夏令时生效时,tm_isdst 可以被设置为1,而当没有夏令时时,tm_isdst 可以被设置为0。值-1表示这不是已知的,并且通常将导致填充正确的状态。

当具有不正确长度的元组被传递给期望 struct_time 的函数或具有错误类型的元素时,产生 TypeError

time.time()

以秒为单位返回以浮点数为单位的时间。请注意,即使时间总是作为浮点数返回,但并不是所有系统都为时间提供比1秒更好的精度。虽然此函数通常返回非递减值,但如果系统时钟已在两次调用之间回退,则它可以返回比上一次调用更低的值。

time.timezone

本地(非DST)时区的偏移量,以UTC以内的秒为单位(西欧大部分地区为负,美国为正,英国为零)。

time.tzname

两个字符串的元组:第一个是本地非DST时区的名称,第二个是本地DST时区的名称。如果没有定义DST时区,则不应使用第二个字符串。

time.tzset()

重置库例程使用的时间转换规则。环境变量 TZ 指定如何完成此操作。

可用性:Unix。

注解

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

TZ 环境变量不应包含空格。

TZ 环境变量的标准格式(为了清晰起见,添加了空格):

std offset [dst [offset [,start[/time], end[/time]]]]

其中组件是:

stddst

三个或更多字母数字,给出时区缩写。这些将被传播到time.tzname

offset

偏移量的格式为:± hh[:mm[:ss]]。这表示添加的本地时间到达UTC的值。如果前面有一个“ - ”,时区是主子午线的东边;否则,它是西。如果在dst之后没有偏移,则假定夏令时比标准时间提前一小时。

start[/time], end[/time]

指示何时更改到DST以及从DST返回。开始和结束日期的格式为以下之一:

Jn

儒略日 n (1 <= n <= 365)。闰年不计算在内,因此,所有年份2月28日是59天,3月1日是60天。

n

基于零的儒略日(0 <= n <= 365)。计算闰年,可参考2月29日。

Mm.n.d

该年 mnd 第A天(0 <= d <= 6)(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')

参见

模块 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 授权。