15.3. time —时间获取和转换

time 模块提供了一些处理时间的函数。对于相关功能, 也可以参考datetime 和 calendar 模块。

尽管本模块总是可用的，但是不是所有的函数在所有的平台上都可用。本模块中定义的大部分函数以相同的名字调用C库函数。有时查看平台的文档会有帮助，因为这些函数的语义因平台而异。

下面顺序解释一些术语和惯例。

• epoch 是时间起始的点。那年1月1日0时，“自epoch以来的时间”是零。Unix的epoch是1970。查看gmtime(0)可以找到epoch是什么。

• 本模块中的函数不能处理epoch之前或者遥远未来的日期和时间。未来的分界点由C库决定；对于Unix，典型的分界点是在2038。

• 千年虫（Y2K）问题：Python依赖平台的C库，一般不会有千年虫问题，因为所有的日期和时间在内部使用自epoch以来的秒数表示。接受struct_time（见下文）的函数一般要求4位数的年份。为了向后兼容，如果模块变量accept2dyear是一个非零的整数，2位数的年份也支持；这个变量被初始化为1除非环境变量PYTHONY2K被设置为非空的字符串，在这种情况下它被初始化为0。因此，你可以在环境中设置PYTHONY2K为一个非空的字符串要求所有年份的输入为4个数字。当接收到两个数字的年份时，它们依据POSIX或者X/Open标准转换：值69-99被映射到1969-1999，值0-68被映射到2000-2068。值100-1899 永远是非法的。注意这是Python 1.5.2(a2)中新引入的；早起的版本，直到Python 1.5.1和1.5.2a1，会将小于1900的年份值加1900。

• UTC 是协调世界时（以前叫格林威治标准时间，或者 GMT）。UTC 不是缩写写错了而是英语和法语之间的折中。

• DST 是夏令时，在一年的部分时间（通常）将时区调整一个小时。DST 的规则很复杂（由当地法律规定）并且可能随着年份变化。C 库有一张包含各地规则的表（通常从系统文件读取）并且是这方面唯一的智慧源泉。

• 各种实时函数的精度可能比它们的值或参数表示的单位要低。例如，在大多数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中的变化：时间的值序列从元组变成struct_time，它带有额外的字段属性名称。

• 使用下面的函数在时间的各种表示之间转换：

  From	To	Use
  seconds since the epoch	struct_time in UTC	gmtime()
  seconds since the epoch	struct_time in local time	localtime()
  struct_time in UTC	seconds since the epoch	calendar.timegm()
  struct_time in local time	seconds since the epoch	mktime()

本模块定义了以下的函数和数据：

time.accept2dyear

指示是否接受两位数的年份值的布尔值。默认为真，但是如果环境变量PYTHONY2K 设置为非空字符串它将设置为假。也可以在运行时刻修改它。

time.altzone

如果被定义，在UTC西部的地区，当地的DST时区在短时间内会有所偏差。如果当地的DST时区在UTC的东部（例如西欧，包括英国），该值为负数。只有在daylight 非零时才使用。

time.asctime([t])

将元组或者由gmtime() 或者localtime()返回的表示时间的struct_time转换成一个24个字符的字符串，形式如下：'Sun Jun 20 23:21:05 1993'。如果没有提供t ，则使用localtime() 返回的当前时间。asctime()没有使用区域信息。

注意

与同名的C 函数不一样，这里没有结尾的换行符。

版本2.1 发生的变化：允许省略t 。

time.clock()

在Unix 上，返回当前的处理器时间，以浮点数秒数表示。精度，事实上就是“处理器时间”含义的定义，取决于同名的C 函数，但是无论在哪一种情况下，它是基准测试Python 或者计时算法使用的函数。

在Windows 上，基于Win32 函 QueryPerformanceCounter()，这个函数返回第一次调用该函数以来逝去的时钟秒数，为一个浮点数。分辨率通常好于一微秒。

time.ctime([secs])

将自epoch以来的时间秒数转换成一个表示当前时间的字符串。如果secs没有提供或者为None，则使用time()返回的当前时间。ctime(secs)等同于asctime(localtime(secs))。ctime()没有使用区域信息。

版本2.1 中发生的变化：允许省略secs 。

版本2.4 中发生的变化：如果secs为None，则使用当前时间。

time.daylight

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

time.gmtime([secs])

将自epoch 以来的时间秒数转换为UTC 的struct_time，它的dst 标记永远为零。如果secs没有提供或者为None，则使用time() 返回的当前时间。秒数的小数部分被忽略。struct_time对象的描述请参见上文。相反的功能请参见calendar.timegm() 。

版本2.1 中发生的变化：允许省略secs。

版本2.4 中发生的变化：如果secs为 None，则使用当前时间。

time.localtime([secs])

类似gmtime() 但是转换成当地时间。如果secs没有提供或者为None，则使用time() 返回的当前时间。当给的时间使用了DST时，dst 标记被设置为1。

版本2.1 中发生的变化：允许省略secs。

版本2.4 中发生的变化：如果secs为None，则使用当前的时间。

time.mktime(t)

localtime()相反的函数。它的参数为struct_time 或者表示当地时间 而不是UTC 时间的完整9-元组（因为需要dst 标记；如果不知道就使用-1作为dst 标记）。它返回一个浮点数，以与time()保持一致。如果输入的值不能表示成一个合法的时间，那么将抛出OverflowError或者ValueError（这依赖于非法的值是被Python还是底层的C库捕获）。它能生成的最早日期依赖于具体的平台。

time.sleep(secs)

挂起执行，时间为给出的秒数。参数可以是浮点数以指明更精确的睡眠时间。真正挂起的时间可能小于要求的时间，因为根据信号捕获程序的执行任何捕获的信号都将终止sleep()。另外，由于系统中其它活动的调动，挂起的时间也可能比要求的时间长一段随机的时间。

time.strftime(format[, t])

将元组或者gmtime()或者localtime()返回的表示时间的struct_time 转换为由参数format指定的字符串。如果没有提供t，则使用localtime() 返回的当前时间。format 必须是一个字符串。如果 t中有任意一个域超出允许的范围，则会抛出ValueError异常。 strftime() 返回一个依赖于区域的字符串；结果可能会通过 strftime(<myformat>).decode(locale.getlocale()[1])转换成unicode。

版本2.1 中的改变：允许省略t。

版本2.4 中的改变：如果t 中的某个域超出范围，则抛出ValueError异常。

版本2.5 中的改变：现在0 在表示时间的元组中的任何位置都是合法的参数； 如果不合法，会被强制转换为一个正确的值。

下面的指令可以嵌入format 字符串中。它们显示时不可以指定可选的域的宽度和精度， 只是被strftime()结果中指定的字符替换：

Directive	Meaning	Notes
%a	区域星期名称的简写。
%A	区域星期名称的全称。
%b	区域月份名称的简写。
%B	区域月份名称的全称。
%c	适合区域的日期和时间的表示。
%d	十进制数[01,31] 表示的一个月的第几天。
%H	十进制数[00,23]表示的小时（24-小时时钟）。
%I	十进制[01,12]表示的小时（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（星期日）,6]表示的星期。
%W	十进制数[00,53]表示的一年中第几个星期（星期一为一星期中的第一天）。新的一年中，第一个星期一之前的所有日子都认为是第0个星期的。	(3)
%x	适合于具体区域的年份表示。
%X	适合于具体区域的时间表示。
%y	十进制数 [00,99]表示的年份，不带有世纪。
%Y	十进制数表示的年份，带有世纪。
%Z	时区名称（如果不存在时区，则为空）。
%%	'%' 字符字面量。

注意：

1. 与strptime() 函数一起使用时，如果使用%I 指令解析小时，%p指令只影响输出的小时字段。
2. 范围确实是0 到61；这是因为有闰秒和（罕见的）双闰秒。
3. 与strptime() 函数一起使用时，%U 和%W 只在指定星期和一年的具体日子才有用。

这里有个例子，与RFC 2822因特网邮件标准兼容的日期格式。[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) 的文档。

在某些平台上，有一个可选的字段宽度和精度的说明可以按一下顺序紧跟在指令开始的'%' 后面；但是这是不可移植的。字段的宽度，除了%j是3以外，通常是2。

time.strptime(string[, format])

根据格式解析一个表示时间的字符串。返回值是struct_time ，和gmtime()或localtime()的返回值一样。

format参数使用的指令和strftime()使用的一样；默认为"%a %b %d %H:%M:%S %Y" ，与ctime()返回的格式匹配。如果string不能根据 format解析出来，或者解析之后又多余的数据，那么将会抛出ValueError异常。当不能推测出准确的值时，用于填充缺失的数据的默认值为 (1900, 1, 1, 0, 0, 0, 0, 1, -1)。

例如：

>>> 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()返回的时间值序列的类型。它是一个带有命名元组 接口的对象：通过索引和属性名都可以访问相应的值。具有以下几个值：

Index	Attribute	Values
0	tm_year	(for example, 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	range [0, 61]; see (2) in strftime() description
6	tm_wday	range [0, 6], Monday is 0
7	tm_yday	range [1, 366]
8	tm_isdst	0, 1 or -1; see below

在版本2.2中新引入。

注意，与C 的结构不同，月份值的范围是[1, 12]不是[0, 11]。年份值将按照上文千年虫问题（Y2K） 的描述处理。将-1 作为夏令时标志的参数传递给mktime() 通常会得到正确的夏令时填充状态。

当一个长度不正确的元组被传递给期望struct_time的函数时， 或者元素的类型错误时，将会抛出TypeError 异常。

time.time()

返回自epoch以来时间的秒数，为浮点数。注意，即使返回的时间永远是浮点数，但是不是所有的系统都提供精度大于1秒的时间。虽然这个函数通常返回非递减值，如果在两次调用期间系统时钟被往回设置了，它可能返回比前一次调用小的值。

time.timezone

本地（非夏令时）时区， in seconds west of UTC（西欧大部分为负值，美国为正值，英国为零）。

time.tzname

A tuple of two strings: the first is the name of the local non-DST timezone, the second is the name of the local DST timezone.If no DST timezone is defined, the second string should not be used.

time.tzset()

Resets the time conversion rules used by the library routines.The environment variable TZ specifies how this is done.

New in version 2.3.

Availability: Unix.

Note

Although in many cases, changing the TZ environment variable may affect the output of functions like localtime() without calling tzset(), this behavior should not be relied on.

The TZ environment variable should contain no whitespace.

TZ 环境变量的标准格式为（为了清晰添加了空格）：

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

其组成部分是：

std and dst

表示时区简写的三个或更多的字母。它们将传入time.tzname 中。

offset

offset 的形式为：± hh[:mm[:ss]]。它只是本地时间到达UTC时需要加上的值。如果前面带有‘-’，则时区在本初子午线的东部；否则在西部。如果dst后面没有offset，那么将假定为夏令时，它比标准时间提前一个小时。

start[/time], end[/time]

指示改成夏令时和从夏令时改回的时间。 开始和结束的日期具有如下的一种形式：

Jn

儒略日的n (1 <= n <= 365)。闰日不计，所以在所有年份中，2月28号是第59天，3月1号是第60天。

n

基于零的儒略日（0 <= n <= 365）。闰日会被计数，可以访问2月29号。

Mm.n.d

第d天（0 <= d <= 6）或者一年第m月的第n 周（1 <= n <= 5，1 <= m <= 12，第5周的意思是“月 m的第d天” ，既可以出现在第四周也可以出现在第五周）。第一周是第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），使用系统的时区信息数据库来指定时区规则更方便（tzfile(5)）。要做到这点，可以设置TZ环境变量到要求的时区数据文件的路径中，相对于‘时区信息’数据库的根目录，通常位于/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')

See also

Module datetime

More object-oriented interface to dates and times.

Module locale

Internationalization services. The locale setting affects the interpretation of many format specifiers in strftime() and strptime().

Module calendar

General calendar-related functions. timegm() is the inverse of gmtime() from this module.

Footnotes

[1]

The use of %Z is now deprecated, but the %z escape that expands to the preferred hour/minute offset is not supported by all ANSI C libraries. Also, a strict reading of the original 1982 RFC 822 standard calls for a two-digit year (%y rather than %Y), but practice moved to 4-digit years long before the year 2000. After that, RFC 822 became obsolete and the 4-digit year has been first recommended by RFC 1123 and then mandated by RFC 2822.