16.3. time - 时间访问和转换

此模块提供各种时间相关功能。有关相关功能，另请参阅datetime和calendar模块。

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

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

  • 时期是时间开始的点。在那一年的1月1日，在0小时，“自时代以来的时间”为零。对于Unix，时代是1970年。要找出时代是什么，看gmtime(0)
  • 此模块中的函数可能无法处理时代之前或远期的日期和时间。未来的截止点由C库决定；对于32位系统，它通常在2038年。
  • 2000年（Y2K）问题：Python取决于平台的C库，它通常没有2000年问题，因为所有的日期和时间都是内部表示为自从时代的秒。当给定%y格式代码时，函数strptime()可以解析2位数年份。当2位年份被解析时，它们根据POSIX和ISO C标准进行转换：值69-99映射到1969-1999，值0-68映射到2000-2068。
  • UTC是协调世界时（以前称为格林威治标准时间，或GMT）。首字母缩略词UTC不是一个错误，而是英语和法语之间的妥协。

  • DST是夏令时，在一部分时间内通过（通常）一个小时调整时区。DST规则是魔法（由当地法律确定），并且可以逐年改变。C库有一个包含本地规则的表（通常它是从系统文件中读取的，以获得灵活性），并且是真正智慧在这方面的唯一来源。

  • 各种实时函数的精度可能小于其中表达其值或自变量的单位的建议。例如。在大多数Unix系统上，时钟“每秒钟”只有50或100次。

  • On the other hand, the precision of time() and sleep() is better than their Unix equivalents: times are expressed as floating point numbers, time() returns the most accurate time available (using Unix gettimeofday() where available), and sleep() will accept a time with a nonzero fraction (Unix select() is used to implement this, where available).

  • The time value as returned by gmtime(), localtime(), and strptime(), and accepted by asctime(), mktime() and strftime(), is a sequence of 9 integers. gmtime()，localtime()和strptime()的返回值还提供了单个字段的属性名称。

    有关这些对象的说明，请参见struct_time。

    Changed in version 3.3: The struct_time type was extended to provide the tm_gmtoff and tm_zone attributes when platform supports corresponding struct tm members.

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

    从至使用
    秒struct_timegmtime()
    秒struct_time在本地时间localtime()
    struct_time秒calendar.timegm()
    struct_time在本地时间秒mktime()

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

time.altzone

默认情况返回一个以秒为单位UTC的本地DST时区偏移量，如果本地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])

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

time.daylight

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

time.get_clock_info(name)

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

结果具有以下属性：

  • 可调：True如果时钟可以自动改变由NTP守护程序）或系统管理员手动，否则False
  • 实现：用于获取时钟值的基础C函数的名称
  • 单调：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()的反函数。Its argument is the struct_time or full 9-tuple (since the dst flag is needed; use -1 as the dst flag if it is unknown) which expresses the time in local time, not UTC. 为了与time()兼容，它返回一个浮点数。如果输入值不能表示为有效时间，则会引发OverflowError或ValueError（这取决于无效值是由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中更改：即使睡眠被信号中断，函数现在也至少睡眠秒，除非信号处理程序引发异常（参见/ t2> PEP 475）。

time.strftime(format[, t])

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

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

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

指示含义笔记
%aLocale的缩写工作日名称。
%ALocale的整个工作日名称。
%b语言环境的缩写月份名称。
%BLocale的完整月份名称。
%c语言环境的适当日期和时间表示。
%d一个十进制数字[01,31]。
%H小时（24小时制），十进制数[00,23]。
%I小时（12小时制）十进制数[01,12]。
%j一年中的十进制数[001,366]。
%m月为十进制数[01,12]。
%M以十进制数分钟[00,59]。
%pLocale相当于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指示与+ HHMM或-HHMM形式的UTC / GMT的正或负时差的时区偏移，其中H表示十进制小时数字，M表示十进制分数字[-23：59，+23：59]。
%Z时区名称（如果没有时区，则不包含字符）。
%%字面值'%'字符。

笔记：

  1. When used with the strptime() function, the %p directive only affects the output hour field if the %I directive is used to parse the hour.
  2. 范围真的是0到61；值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）文档。

在某些平台上，可选字段宽度和精度规范可以紧跟在以下顺序的指令的初始'%'之后：这也不便携。除了%j，字段宽度通常为2，其中它为3。

time.strptime(string[, format])

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

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(). 如果string不能根据格式解析，或者如果解析后有过多的数据，则会引发ValueError。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")   
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

The type of the time value sequence returned by gmtime(), localtime(), and strptime(). It is an object with a named tuple interface: values can be accessed by index and by attribute name. The following values are present:

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
N/A tm_zone abbreviation of timezone name
N/A tm_gmtoff offset east of UTC in seconds

Note that unlike the C structure, the month value is a range of [1, 12], not [0, 11].

In calls to mktime(), tm_isdst may be set to 1 when daylight savings time is in effect, and 0 when it is not. A value of -1 indicates that this is not known, and will usually result in the correct state being filled in.

When a tuple with an incorrect length is passed to a function expecting a struct_time, or having elements of the wrong type, a TypeError is raised.

在版本3.3中更改： tm_gmtoff和tm_zone属性可用于具有C库的平台，支持/ t6> tm。

time.time()

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

time.timezone

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

time.tzname

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

time.tzset()

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

可用性：Unix。

注意

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.

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返回。开始和结束日期的格式为以下之一：

J n
The Julian day n (1 <= n <= 365). 闰年不计算在内，因此，所有年份2月28日是59天，3月1日是60天。
n
The zero-based Julian day (0 <= n <= 365). 计算闰年，可参考2月29日。
M m 。 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). 第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），但练习移至4位数年早在2000年之前。之后， RFC 822已过时，并且 RFC 1123首先推荐4位年份，然后由 RFC 2822强制。