# 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_time` | `gmtime()`
  秒 | `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)

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

  - `'clock'`：`time.clock()`
  - `'monotonic'`：`time.monotonic()`
  - `'perf_counter'`：`time.perf_counter()`
  - `'process_time'`：`time.process_time()`
  - `'time'`：`time.time()`

  结果具有以下属性：

  - 可调：`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()`结果中指示的字符替换：

  指示 | 含义 | 笔记
  --- | --- | ---
  `%a` | Locale的缩写工作日名称。 |
  `%A` | Locale的整个工作日名称。 |
  `%b` | 语言环境的缩写月份名称。 |
  `%B` | Locale的完整月份名称。 |
  `%c` | 语言环境的适当日期和时间表示。 |
  `%d` | 一个十进制数字[01,31]。 |
  `%H` | 小时（24小时制），十进制数[00,23]。 |
  `%I` | 小时（12小时制）十进制数[01,12]。 |
  `%j` | 一年中的十进制数[001,366]。 |
  `%m` | 月为十进制数[01,12]。 |
  `%M` | 以十进制数分钟[00,59]。 |
  `%p` | Locale相当于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强制。