15.3. 时间-时间访问和转化

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

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

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

• • epoch *是时间开始的点。该年 1 月 1 日的 0 时，“自纪元以来的时间”为零。对于 Unix，纪元是 1970.要了解纪元是什么，请查看gmtime(0)。

• 该模块中的Function不处理在纪元之前或将来的日期和时间。Future 的临界点由 C 库确定；对于 Unix，通常在 2038 年。

• 2000 年(Y2K)问题 ：Python 依赖于平台的 C 库，该库通常没有 2000 年问题，因为所有日期和时间都在内部以秒表示。接受struct_time(见下文)的Function通常需要 4 位数字的年份。为了向后兼容，如果模块变量accept2dyear是非零整数，则支持 2 位数的年份；否则，不支持。除非环境变量 PYTHONY2K设置为非空字符串，否则此变量将初始化为1，在这种情况下，它将初始化为0。因此，您可以在环境中将 PYTHONY2K设置为非空字符串，以要求所有年份 Importing 都为 4 位数字年份。接受两位数的年份时，将根据 POSIX 或 X/Open 标准对其进行转换：将值 69-99Map 到 1969-1999，将值 0-68Map 到 2000-2068.值 100-1899 始终是非法的。

• 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。

在版本 2.2 中进行了更改：时间值序列从 Tuples 更改为struct_time，并添加了字段的属性名称。

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

From	To	Use
自纪元以来的秒数	UTC struct_time	gmtime()
自纪元以来的秒数	当地时间struct_time	localtime()
UTC struct_time	自纪元以来的秒数	calendar.timegm()
当地时间struct_time	自纪元以来的秒数	mktime()

该模块定义了以下Function和数据项：

• time. accept2dyear

  • 布尔值，指示是否接受两位数的年份值。默认情况下为 true，但如果环境变量 PYTHONY2K已设置为非空字符串，则将其设置为 false。也可以在运行时对其进行修改。

• time. altzone

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

• time. asctime([* t *])

  • 将表示gmtime()或localtime()返回的时间的 Tuples 或struct_time转换为以下格式的 24 个字符的字符串：'Sun Jun 20 23:21:05 1993'。如果未提供* t *，则使用localtime()返回的当前时间。 asctime()不使用语言环境信息。

在版本 2.1 中更改：允许Ellipsis* t *。

• time. clock ( )
  • 在 Unix 上，以秒为单位返回当前处理器时间，以浮点数表示。精度(实际上是“处理器时间”的含义的确切定义)取决于同名 C 函数的精度，但无论如何，这是用于基准化 Python 或计时算法的函数。

在 Windows 上，基于 Win32 函数QueryPerformanceCounter()，此函数返回自首次调用此函数以来经过的时间(以秒为单位)，以浮点数表示。分辨率通常优于一微秒。

• time. ctime([秒])
  • 将自纪元以来的时间(以秒为单位)转换为表示本地时间的字符串。如果未提供* secs *或None，则使用time()返回的当前时间。 ctime(secs)等效于asctime(localtime(secs))。 ctime()不使用语言环境信息。

在版本 2.1 中更改：允许* secs *Ellipsis。

在版本 2.4 中更改：如果* secs *为None，则使用当前时间。

• time. daylight

  • 如果定义了 DST 时区，则为非零值。

• time. gmtime([秒])

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

在版本 2.1 中更改：允许* secs *Ellipsis。

在版本 2.4 中更改：如果* secs *为None，则使用当前时间。

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

在版本 2.1 中更改：允许* secs *Ellipsis。

在版本 2.4 中更改：如果* secs *为None，则使用当前时间。

• time. mktime(* t *)

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

• time. sleep(秒)

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

• time. strftime(* format * [，* t *])

  • 将表示gmtime()或localtime()返回的时间的 Tuples 或struct_time转换为* format 参数指定的字符串。如果未提供 t ，则使用localtime()返回的当前时间。 格式必须为字符串。如果 t *中的任何字段超出允许范围，则引发ValueError。 strftime()返回与语言环境相关的字节字符串；pass执行strftime(<myformat>).decode(locale.getlocale()[1])可以将结果转换为 unicode。

在版本 2.1 中更改：允许Ellipsis* t *。

在版本 2.4 中进行了更改：如果* t *中的字段超出范围，则引发ValueError。

在版本 2.5 中进行了更改：0 现在是时间 Tuples 中任何位置的合法参数；如果通常是非法的，则将该值强制为正确的值。

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

Directive	Meaning	Notes
%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	时区名称(如果不存在时区，则没有字符)。
%%	Literals'%'字符。

Notes:

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

• 范围实际上是0至61;这占 leap 秒和(非常罕见的)双 leap 秒。

• 当与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)。

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索引和属性名称访问值。存在以下值：

Index	Attribute	Values
0	tm_year	(例如，1993 年)
1	tm_mon	range [1, 12]
2	tm_mday	range [1, 31]
3	tm_hour	range [0, 23]
4	tm_min	range [0, 59]
5	tm_sec	范围[0，61];参见strftime()说明中的 (2)
6	tm_wday	范围[0，6]，星期一为 0
7	tm_yday	range [1, 366]
8	tm_isdst	0，1 或-1;见下文

2.2 版中的新Function。

请注意，与 C 结构不同，月份值是[1，12]的范围，而不是[0，11]。将按照上面的2000 年(Y2K)问题所述处理年份值。

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

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

• time. time ( )

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

• time. timezone

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

• time. tzname

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

• time. tzset ( )

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

2.3 版的新Function。

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

Footnotes

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