Python 内置 time 模块 API 中文档案

15.3. time — Time access and conversions

        Documentation : https://docs.python.org/2.7/library/time.html

        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().
        Note : Unlike the C function of the same name, there is no trailing newline.
        Changed in version 2.1: Allowed t to be omitted.

        将一个由 gmtime() 或 localtime() 返回的以 struct_time 元组表示的时间转换为24字符的时间表示，如下格式: 'Sun Jun 20 23:21:05 1993'。如果参数 t 未给定，系统将会使用由 localtime() 返回的值。asctime() 不关心时区信息。
        注意：与 C 语言中的同名函数不同，这里没有在结尾追加新行。
        2.1 版本变更：允许 t 被省略，即空参数。

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.
        On Windows, this function returns wall-clock seconds elapsed since the first call to this function, as a floating point number, based on the Win32 function QueryPerformanceCounter(). The resolution is typically better than one microsecond.

time.ctime([secs])

        Convert a time expressed in seconds since the epoch to a string representing local time. If secs is not provided or None, the current time as returned by time() is used. ctime(secs) is equivalent to asctime(localtime(secs)). Locale information is not used by ctime().
        Changed in version 2.1: Allowed secs to be omitted.
        Changed in version 2.4: If secs is None, the current time is used.
        将一个从 epoch 时间（'1970-01-01 00:00:00 UTC'）开始经历的秒数，转化为字符串表示的当地时间。如果参数 secs 未指定，使用 time() 返回的当前时间。ctime(secs) 作用等同于 asctime(localtime(secs)) 。ctime() 不使用时区信息。

time.daylight

        Nonzero if a DST timezone is defined.
        如果 DST 时区已设置，则该值非零。

time.gmtime([secs])

        Convert a time expressed in seconds since the epoch to a struct_time in UTC in which the dst flag is always zero. If secs is not provided or None, the current time as returned by time() is used. Fractions of a second are ignored. See above for a description of the struct_time object. See calendar.timegm() for the inverse of this function.
        Changed in version 2.1: Allowed secs to be omitted.
        Changed in version 2.4: If secs is None, the current time is used.
        将一个从 epoch 时间（'1970-01-01 00:00:00 UTC'）开始经历的秒数，转化为 struct_time 结构的 UTC 时间，且 dst 标志为0。如果参数 secs 未指定或为 None，则使用 time() 返回的当前时间。秒的小数部分将会被忽略。

time.localtime([secs])

        Like gmtime() but converts to local time. If secs is not provided or None, the current time as returned by time() is used. The dst flag is set to 1 when DST applies to the given time.
        Changed in version 2.1: Allowed secs to be omitted.
        Changed in version 2.4: If secs is None, the current time is used.
        像 gmtime() 一样转化当地时间为 struct_time 结构。

time.mktime(t)

        This is the inverse function of 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. It returns a floating point number, for compatibility with time(). If the input value cannot be represented as a valid time, either OverflowError or ValueError will be raised (which depends on whether the invalid value is caught by Python or the underlying C libraries). The earliest date for which it can generate a time is platform-dependent.
        与 localtime() 功能相反，它的参数是完整的９个参数的元组，用本地时间表示而不是UTC。返回值是浮点数值，与 time() 兼容。如果输入值不能被表示成正确的元组时间，将会抛出溢出错误或值错误。

time.sleep(secs)

        Suspend execution 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 depedent byte string; the result may be converted to unicode by doing strftime().decode(locale.getlocale()[1]).
        将一个元组或由 gmtime()、localtime()返回的 struct_time 表示的时间，转化成为 format 格式的时间。如果为提供参数 t，默认使用 localtime() 返回的时间值。format 为字符串形式，如果 t 中有任何值超过范围将会抛出 ValueError 异常。
        Changed in version 2.1: Allowed t to be omitted.
        Changed in version 2.4: ValueError raised if a field in t is out of range.
        Changed in version 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.
        The following directives can be embedded in the format string. They are shown without the optional field width and precision specification, and are replaced by the indicated characters in the strftime() result:
        如下列出的字符可以放到 format 串中。他们被有可选的参数用于指定显示的宽度以及精度，并在 strftime() 返回的结果中被要指示的字符代替。

DirectiveMeaningNotes%aLocale’s abbreviated weekday name. %ALocale’s full weekday name. %bLocale’s abbreviated month name. %BLocale’s full month name. %cLocale’s appropriate date and time representation. %dDay of the month as a decimal number [01,31]. %HHour (24-hour clock) as a decimal number [00,23]. %IHour (12-hour clock) as a decimal number [01,12]. %jDay of the year as a decimal number [001,366]. %mMonth as a decimal number [01,12]. %MMinute as a decimal number [00,59]. %pLocale’s equivalent of either AM or PM.(1)%SSecond as a decimal number [00,61].(2)%UWeek 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)%wWeekday as a decimal number [0(Sunday),6]. %WWeek 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)%xLocale’s appropriate date representation. %XLocale’s appropriate time representation. %yYear without century as a decimal number [00,99]. %YYear with century as a decimal number. %ZTime zone name (no characters if no time zone exists). %%A literal '%' character. 

        Notes:
        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.The range really is 0 to 61; this accounts for leap seconds and the (very rare) double leap seconds.
        3.When used with the strptime() function, %U and %W are only used in calculations when the day of the week and the year are specified.
        1.使用 strptime() 函数时，只有在 %I 指令来显示小时时（12小时制），%p 指令（显示AM/PM）才会有效果。
        2.实际的范围是0到61，这是为闰秒或双闰秒设置的。
        3.使用 strptime() 函数时，%u 和 %w 只有在某天属于一周的第几天和一年的第几天指定时才有效。
        Here is an example, a format for dates compatible with that specified in the RFC 2822 Internet email standard. [1]

>>> from time import gmtime, strftime>>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())'Thu, 28 Jun 2001 14:17:15 +0000'

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().
        将一个字符串依据给定的格式转化成为时间值，返回结果是类似 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(). 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).

        For example:

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

        Support for the %Z directive is based on the values contained in tzname and whether daylight is true. Because of this, it is platform-specific except for recognizing UTC and GMT which are always known (and are considered to be non-daylight savings timezones).
        Only the directives specified in the documentation are supported. Because strftime() is implemented per platform it can sometimes offer more directives than those listed. But strptime() is independent of any platform and thus does not necessarily support all directives available that are not documented as supported.

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:

IndexAttributeValues0tm_year(for example, 1993)1tm_monrange [1, 12]2tm_mdayrange [1, 31]3tm_hourrange [0, 23]4tm_minrange [0, 59]5tm_secrange [0, 61]; see (2) in strftime()description6tm_wdayrange [0, 6], Monday is 07tm_ydayrange [1, 366]8tm_isdst0, 1 or -1; see below

        New in version 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. A -1 argument as the daylight savings flag, passed to mktime() will usually result in the correct daylight savings state to be 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.

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.