15.3. time — 时间的访问和转换

该模块提供了各种时间相关的函数。相关功能还可以参阅 datetime 和 calendar 模块。

尽管此模块始终可用，但并非所有平台上都提供所有功能。 此模块中定义的大多数函数调用都具有相同名称的平台C库函数。 因为这些函数的语义因平台而异,所以使用时最好查阅平台相关文档。

下面是一些术语和惯例的解释.

  • The epoch is the point where the time starts. On January 1st of that year, at 0 hours, the “time since the epoch” is zero. For Unix, the epoch is 1970. To find out what the epoch is, look at gmtime(0).
  • The functions in this module do not handle dates and times before the epoch or far in the future. The cut-off point in the future is determined by the C library; for Unix, it is typically in 2038.
  • Year 2000 (Y2K) issues: Python depends on the platform’s C library, which generally doesn’t have year 2000 issues, since all dates and times are represented internally as seconds since the epoch. Functions accepting a struct_time (see below) generally require a 4-digit year. For backward compatibility, 2-digit years are supported if the module variable accept2dyear is a non-zero integer; this variable is initialized to 1 unless the environment variable PYTHONY2K is set to a non-empty string, in which case it is initialized to 0. Thus, you can set PYTHONY2K to a non-empty string in the environment to require 4-digit years for all year input. When 2-digit years are accepted, they are converted according to the POSIX or X/Open standard: values 69-99 are mapped to 1969-1999, and values 0–68 are mapped to 2000–2068. Values 100–1899 are always illegal.
  • UTC是协调世界时（以前称为格林威治标准时间，或GMT）。缩写UTC不是错误，而是英语和法语之间的妥协。

  • DST是夏令时，在一年中的一部分时间（通常）调整时区一小时。 DST规则很神奇（由当地法律确定），并且每年都会发生变化。 C 库有一个包含本地规则的表（通常是从系统文件中读取以获得灵活性），并且在这方面是True Wisdom的唯一来源。

  • 各种实时函数的精度可能低于表示其值或参数的单位所建议的精度。例如，在大多数Unix系统上，时钟 “ticks” 仅为每秒50或100次。

  • 另一方面， time() 和 sleep() 的精度优于它们的Unix等价物：时间表示为浮点数，time() 返回最准确的时间 （使用Unix gettimeofday() 如果可用），并且 sleep() 将接受非零分数的时间（Unix select() 用于实现此功能，如果可用）。

  • The time value as returned by gmtime(), localtime(), and strptime(), and accepted by asctime(), mktime() and strftime(), may be considered as a sequence of 9 integers. The return values of gmtime(), localtime(), and strptime() also offer attribute names for individual fields.

    请参阅 struct_time 以获取这些对象的描述。

    在 2.2 版更改: The time value sequence was changed from a tuple to a struct_time, with the addition of attribute names for the fields.

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

    从 到 使用
    seconds since the epoch UTC 的 struct_time gmtime()
    seconds since the epoch 本地时间的 struct_time localtime()
    UTC 的 struct_time seconds since the epoch calendar.timegm()
    本地时间的 struct_time seconds since the epoch mktime()

The module defines the following functions and data items:

time.accept2dyear

Boolean value indicating whether two-digit year values will be accepted. This is true by default, but will be set to false if the environment variable PYTHONY2K has been set to a non-empty string. It may also be modified at run time.

time.altzone

The offset of the local DST timezone, in seconds west of UTC, if one is defined. This is negative if the local DST timezone is east of UTC (as in Western Europe, including the UK). Only use this if daylight is nonzero.

time.asctime([t])

Convert a tuple or struct_time representing a time as returned by gmtime() or localtime() to a 24-character string of the following form: 'Sun Jun 20 23:21:05 1993'. If t is not provided, the current time as returned by localtime() is used. Locale information is not used by asctime().

注解

Unlike the C function of the same name, there is no trailing newline.

在 2.1 版更改: Allowed t to be omitted.

time.clock()

On Unix, return the current processor time as a floating point number expressed in seconds. The precision, and in fact the very definition of the meaning of “processor time”, depends on that of the C function of the same name, but in any case, this is the function to use for benchmarking Python or timing algorithms.

在Windows上，此函数返回自第一次调用此函数以来经过的 wallclock 秒数，作为浮点数，基于Win32函数 QueryPerformanceCounter()。分辨率通常优于1微秒。

time.ctime([secs])

将自 seconds since the epoch 表示的时间转换为表示本地时间的字符串。如果未提供 secs 或为 None，则使用由 time() 返回的当前时间。 ctime(secs) 相当于 asctime(localtime(secs)) 。区域信息不被 ctime() 使用。

在 2.1 版更改: Allowed secs to be omitted.

在 2.4 版更改: If secs is None, the current time is used.

time.daylight

Nonzero if a DST timezone is defined.

time.gmtime([secs])

将 seconds since the epoch 为单位的时间转换为UTC的 struct_time ，其中dst标志始终为零。如果未提供 secs 或为 None ，则使用由 time() 返回的当前时间。忽略一秒的分数。有关 struct_time 对象的说明，请参见上文。有关此函数的反函数，请参阅 calendar.timegm() 。

在 2.1 版更改: Allowed secs to be omitted.

在 2.4 版更改: If secs is None, the current time is used.

time.localtime([secs])

与 gmtime() 相似但转换为当地时间。如果未提供 secs 或为 None ，则使用由 time() 返回的当前时间。当 DST 适用于给定时间时，dst标志设置为 1 。

在 2.1 版更改: Allowed secs to be omitted.

在 2.4 版更改: If secs is None, the current time is used.

time.mktime(t)

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

time.sleep(secs)

Suspend execution of the current thread for the given number of seconds. The argument may be a floating point number to indicate a more precise sleep time. The actual suspension time may be less than that requested because any caught signal will terminate the sleep() following execution of that signal’s catching routine. Also, the suspension time may be longer than requested by an arbitrary amount because of the scheduling of other activity in the system.

time.strftime(format[, t])

Convert a tuple or struct_time representing a time as returned by gmtime() or localtime() to a string as specified by the format argument. If t is not provided, the current time as returned by localtime() is used. format must be a string. ValueError is raised if any field in t is outside of the allowed range. strftime() returns a locale dependent byte string; the result may be converted to unicode by doing strftime(<myformat>).decode(locale.getlocale()[1]).

在 2.1 版更改: Allowed t to be omitted.

在 2.4 版更改: ValueError raised if a field in t is out of range.

在 2.5 版更改: 0 is now a legal argument for any position in the time tuple; if it is normally illegal the value is forced to a correct one.

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

指令 意义 注释
%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 Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0. (3)
%w 十进制数 [0(星期日),6] 表示的周中日。  
%W Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Monday are considered to be in week 0. (3)
%x 本地化的适当日期表示。  
%X 本地化的适当时间表示。  
%y 十进制数 [00,99] 表示的没有世纪的年份。  
%Y 十进制数表示的带世纪的年份。  
%Z 时区名称（如果不存在时区，则不包含字符）。  
%% 字面的 '%' 字符。  

注释:

  1. 当与 strptime() 函数一起使用时，如果使用 %I 指令来解析小时， %p 指令只影响输出小时字段。
  2. The range really is 0 to 61; this accounts for leap seconds and the (very rare) double leap seconds.
  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])

Parse a string representing a time according to a format. The return value is a struct_time as returned by gmtime() or localtime().

The format parameter uses the same directives as those used by strftime(); it defaults to "%a %b %d %H:%M:%S %Y" which matches the formatting returned by ctime(). If string cannot be parsed according to format, or if it has excess data after parsing, ValueError is raised. The default values used to fill in any missing data when more accurate values cannot be inferred are (1900, 1, 1, 0, 0, 0, 0, 1, -1).

例如:

>>> import time
>>> time.strptime("30 Nov 00", "%d %b %y")   # doctest: +NORMALIZE_WHITESPACE
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 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]； 见 strftime() 介绍中的 (2)
6 tm_wday range [0, 6] ，周一为 0
7 tm_yday range [1, 366]
8 tm_isdst 0, 1 或 -1；如下所示

2.2 新版功能.

Note that unlike the C structure, the month value is a range of [1, 12], not [0, 11]. A year value will be handled as described under Year 2000 (Y2K) issues above.

在调用 mktime() 时， tm_isdst 可以在夏令时生效时设置为1，而在夏令时不生效时设置为0。 值-1表示这是未知的，并且通常会导致填写正确的状态。

当一个长度不正确的元组被传递给期望 struct_time 的函数，或者具有错误类型的元素时，会引发 TypeError 。

time.time()

Return the time in seconds since the epoch as a floating point number. Note that even though the time is always returned as a floating point number, not all systems provide time with a better precision than 1 second. While this function normally returns non-decreasing values, it can return a lower value than a previous call if the system clock has been set back between the two calls.

time.timezone

The offset of the local (non-DST) timezone, in seconds west of UTC (negative in most of Western Europe, positive in the US, zero in the UK).

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

重置库例程使用的时间转换规则。环境变量 TZ 指定如何完成。它还将设置变量 tzname （来自 TZ 环境变量）， timezone （UTC的西部非DST秒）， altzone （UTC以西的DST秒）和 daylight （如果此时区没有任何夏令时规则则为0，如果有夏令时适用的时间，无论过去、现在或未来，则为非零）。

2.3 新版功能.

Availability: Unix.

注解

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

TZ 不应该包含空格。

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
Julian日 n （1 <= n <= 365）。闰日不计算在内，因此在所有年份中，2月28日是第59天，3月1日是第60天。
n
从零开始的Julian日（0 <= n <= 365）。 闰日计入，可以引用2月29日。
Mm.n.d
The d’th day (0 <= d <= 6) or week n of month m of the year (1 <= n <= 5, 1 <= m <= 12, where week 5 means “the last d day in month m” which may occur in either the fourth or the fifth week). Week 1 is the first week in which the d’th day occurs. Day zero is Sunday.

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 环境变量设置为所需时区数据文件的路径，相对于系统 ‘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 强制执行。