time

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

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

为了解释一些术语和惯例。

• 该时期是时间开始点在哪里。当年的1月1日，0时，“时代以来的时间”为零。对于Unix来说，这个时代是1970年。要了解这个时代是什么，请看看gmtime(0)。

• 本模块中的功能不处理时代之前或未来的日期和时间。未来的截止点由C库确定; 对于Unix，它通常在2038年。

• 2000年（Y2K）问题：Python取决于平台的C库，它通常没有2000年问题，因为所有日期和时间都在内部表示为从时代开始的秒数。接受a struct_time（见下文）的函数通常需要4位数的年份。为了向后兼容，如果模块变量accept2dyear是非零整数，则支持2位数年份; 这个变量被初始化为1除非环境变量PYTHONY2K被设置为非空字符串，在这种情况下，它被初始化为0。因此，你可以设置PYTHONY2K转换为环境中的非空字符串，以便全年输入需要4位数的年份。当接受2位数年份时，它们根据POSIX或X / Open标准进行转换：将值69-99映射到1969-1999，将值0-68映射到2000-2068。值100-1899始终是非法的。

• UTC的协调世界时（以前称为格林威治标准时间，或GMT）。UTC的缩写不是一个错误，而是英法之间的妥协。

• 夏令时是夏令时，是在一年中部分时间（通常）一小时调整时区的时间。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中已更改：时间值序列已从元组更改为a struct_time，并添加了字段的属性名称。

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

从	至	使用
自纪元以来的秒数	struct_time 以UTC表示	gmtime()
自纪元以来的秒数	struct_time 在当地时间	localtime()
struct_time 以UTC表示	自纪元以来的秒数	calendar.timegm()
struct_time 在当地时间	自纪元以来的秒数	mktime()

函数

time.asctime([t])

转换的元组或struct_time表示如通过返回的时间 gmtime()或localtime()到以下形式的字符串：。如果未提供t，则使用返回的当前时间。区域设置信息不被使用 。'Sun Jun 20 23:21:05 1993'localtime()asctime()

注意

与同名的C函数不同，asctime()不会添加尾随换行符。

time.clock()

在Unix上，将当前处理器时间返回为以秒为单位的浮点数。精确性，实际上“处理器时间”含义的定义取决于具有相同名称的C函数的精确度。

在Windows上，此函数根据Win32函数返回自第一次调用该函数以来的挂钟时间，作为浮点数QueryPerformanceCounter()。分辨率通常优于1微秒。

自3.3版弃用：此功能的行为取决于平台：根据您的要求使用 perf_counter()或process_time()取而代之，以获得定义良好的行为。

time.clock_getres(clk_id)

返回指定时钟clk_id的分辨率（精度）。有关clk_id的可接受值列表，请参阅 时钟ID常量。

可用性：Unix。

3.3版本的新功能

time.clock_gettime(clk_id)

返回指定时钟clk_id的时间。有关clk_id的可接受值列表，请参阅 时钟ID常量。

可用性：Unix。

3.3版本的新功能

time.clock_settime(clk_id，time)

设置指定时钟clk_id的时间。目前， CLOCK_REALTIME是clk_id唯一可接受的值。

可用性：Unix。

3.3版本的新功能

time.ctime([secs])

将时间以秒为单位的时间转换为表示本地时间的字符串。如果没有提供secs，或者使用None返回的当前时间time()。 ctime(secs)相当于 asctime(localtime(secs))。区域设置信息不被使用ctime()。

time.get_clock_info(name)

获取有关指定时钟的信息作为名称空间对象。支持的时钟名称和相应的函数来读取它们的值是：

'clock'： time.clock()

'monotonic'： time.monotonic()

'perf_counter'： time.perf_counter()

'process_time'： time.process_time()

'time'： time.time()

结果具有以下属性：

• 可调：True如果时钟可以自动更改（例如通过NTP守护进程）或由系统管理员手动更改，False否则
• 实现：用于获取时钟值的底层C函数的名称。请参阅时钟ID常量以获取可能的值。
• 单调：True如果时钟不能倒退， False否则
• 分辨率：以秒为单位的时钟分辨率(float)

3.3版本的新功能

time.gmtime([secs])

将从时期开始以秒为单位的时间转换为struct_timeUTC中dst标志始终为零的时间。如果没有提供secs，或者使用None返回的当前时间time()。一秒钟的分数被忽略。参见上面的struct_time对象描述 。请参阅calendar.timegm()此功能的反面。

time.localtime([secs])

像gmtime()但转换到当地时间。如果没有提供secs，或者 使用None返回的当前时间time()。1当DST适用于给定时间时，dst标志被设置为。

time.mktime(t)

这是与之相反的功能localtime()。它的参数是 struct_time或满9元组（因为需要DST标志;使用-1 ，如果它是未知的DST标志），这表示在时间本地时间，而不是UTC。它返回一个浮点数，与之兼容time()。如果输入值不能被表示为有效时间， OverflowError或者ValueError将被提升（这取决于无效值是被Python还是底层C库捕获）。它可以产生时间的最早日期是平台相关的。

time.monotonic()

返回单调时钟的值（小数秒），即不能倒退的时钟。时钟不受系统时钟更新的影响。返回值的参考点未定义，因此只有连续调用结果之间的差异才有效。

在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中更改：即使睡眠被信号中断，该函数现在也会睡眠至少秒，除非信号处理程序引发异常（请参阅PEP 475为理由）。

time.strftime(format[,t])

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

0是时间元组中任何位置的合法参数; 如果它通常是非法的，那么这个值就会被强制为一个正确的值。

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

指示	含义	注意
%a	区域设置的缩写星期几名称。
%A	Locale的完整星期几名称。
%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	没有century作为十进制数的年份[00,99]。
%Y	century作为十进制数字。
%z	时区偏移量指示格式为+ HHMM或-HHMM的UTC/GMT的正负时差，其中H表示十进制小时数字，M表示十进制分钟数 [-23:59, +23:59]。
%Z	时区名称（如果不存在时区，则不显示字符）。
%%	字面'%'字符。

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

• 范围确实是0到61; 这占了闰秒和（非常罕见的）双闰秒。

• 当与使用strptime()功能，%U并且%W指定了一周，一年中的一天，在计算仅使用。

下面是一个例子，日期格式与 RFC 2822Internet电子邮件标准中指定的格式兼容。[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])

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

该格式参数使用相同的指令那些由使用strftime(); 它默认为"%a %b %d %H:%M:%S %Y"匹配返回的格式ctime()。如果字符串不能根据格式进行分析，或者在解析后有多余的数据，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()。它是具有命名元组接口的对象：值可以通过索引和属性名称来访问。以下值存在：

指数	属性	值
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	范围0,61; 请参阅（2）中的strftime（）描述
6	tm_wday	范围0，6，星期一为0
7	tm_yday	范围1,366
8	tm_isdst的	0,1或-1; 见下文

2.2版本中的新功能。

请注意，与C结构不同，月份值的范围为1,12，而不是0,11。年份值将按照上述2000年（Y2K）问题中的描述进行处理。

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

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

time.time()

自纪元起以秒为单位返回浮点数的时间。请注意，即使时间总是以浮点数形式返回，但并非所有系统的时间精度都比1秒高。虽然此函数通常返回非递减值，但如果系统时钟已在两次调用之间回退，则它可以返回比先前调用更低的值。

time.timezone

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

time.tzname

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

time.tzset()

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

2.3版本的新功能。

可用性：Unix。

注意

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

该TZ环境变量应该包含没有空格。

TZ环境变量的标准格式是（为清楚起见，添加了空格）：

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

组件是：

std and dst三个或更多的字母数字提供时区缩写。这些将传播到time.tzname offset偏移量的形式为：± hh[:mm[:ss]]。这表示该值增加了当地时间到达UTC。如果前面有' - '，则时区在Prime Meridian的东边; 否则，它是西方的。如果在dst之后没有偏移，则夏季时间假定为比标准时间提前一个小时。start[/time], end[/time]

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

Jn朱利安日n（1 <= n <= 365）。闰日不计算在内，所以在所有年份中，2月28日是59天，3月1日是60天n。零基Julian日（0 <= n <= 365）。对闰日进行计数，可以参考2月29日。Mm.n.d第d天（0 <= d <= 6）或当年第m月的第n周（1 <= n <= 5,1 = 米 <= 12，其中每周5种手段“的最后d一天月米 ”，其可以在任一第四或第五周发生）。1周是其中的第一个星期d “日天发生。第零天是星期天。

timeoffset除了不允许使用前导符号（' - '或'+'）以外，格式相同。如果没有给出时间，默认是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')

也可以看看

Module datetime 面向日期和时间的面向对象的接口。 Module locale 国际化服务。区域设置会影响许多格式说明的解释strftime()和strptime()。 Module calendar 一般日历相关功能。timegm()是gmtime()这个模块的反面。

脚注

1	现在不推荐使用％Z，但所有ANSI C库都不支持使用扩展为首选小时/分钟偏移量的％z转义符。此外，严格阅读最初的1982年RFC 822标准需要两位数的年份（％y而不是％Y），但实践在2000年之前移到了4位数年。之后，RFC 822变得过时了， 4位数的年份首先由RFC 1123推荐，然后由RFC 2822授权。