This module provides various time-related functions. It is always available, but not all functions are available on all platforms.
An explanation of some terminology and conventions is in order.
accept2dyearis a non-zero integer; this variable is initialized to
1unless 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. Note that this is new as of Python 1.5.2(a2); earlier versions, up to Python 1.5.1 and 1.5.2a1, would add 1900 to year values below 1900.
The time tuple as returned by gmtime(), localtime(), and strptime(), and accepted by asctime(), mktime() and strftime(), is a tuple of 9 integers:
||second||range [0,61]; see (1) in strftime() description|
||weekday||range [0,6], Monday is 0|
||Julian day||range [1,366]|
||daylight savings flag||0, 1 or -1; see below|
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
daylight savings flag, passed to mktime() will usually
result in the correct daylight savings state to be filled in.
The module defines the following functions and data items:
'Sun Jun 20 23:21:05 1993'. If tuple is not provided, the current time as returned by localtime() is used. Note: unlike the C function of the same name, there is no trailing newline. Changed in version 2.1: Allowed tuple to be omitted.
On Windows, this function returns the nearest approximation to wall-clock time since the first call to this function, based on the Win32 function QueryPerformanceCounter(). The resolution is typically better than one microsecond.
ctime(secs)is equivalent to
asctime(localtime(secs)). Changed in version 2.1: Allowed secs to be omitted.
1when DST applies to the given time. Changed in version 2.1: Allowed secs to be omitted.
-1as 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, OverflowError is raised.
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:
||Locale's abbreviated weekday name.|
||Locale's full weekday name.|
||Locale's abbreviated month name.|
||Locale's full month name.|
||Locale's appropriate date and time representation.|
||Day of the month as a decimal number [01,31].|
||Hour (24-hour clock) as a decimal number [00,23].|
||Hour (12-hour clock) as a decimal number [01,12].|
||Day of the year as a decimal number [001,366].|
||Month as a decimal number [01,12].|
||Minute as a decimal number [00,59].|
||Locale's equivalent of either AM or PM.|
||Second as a decimal number [00,61].||(1)|
||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.|
||Weekday as a decimal number [0(Sunday),6].|
||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 Sunday are considered to be in week 0.|
||Locale's appropriate date representation.|
||Locale's appropriate time representation.|
||Year without century as a decimal number [00,99].|
||Year with century as a decimal number.|
||Time zone name (or by no characters if no time zone exists).|
||A literal "%" character.|
61; this accounts for leap seconds and the (very rare) double leap seconds.
Here is an example, a format for dates compatible with that specified in the RFC 2822 Internet email standard. 6.1
>>> from time import gmtime, strftime >>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime()) 'Thu, 28 Jun 2001 14:17:15 +0000'
Additional directives may be supported on certain platforms, but only the ones listed here have a meaning standardized by ANSI C.
On some platforms, an optional field width and precision
specification can immediately follow the initial "%" of a
directive in the following order; this is also not portable.
The field width is normally 2 except for
%j where it is 3.
"%a %b %d %H:%M:%S %Y"which matches the formatting returned by ctime(). The same platform caveats apply; see the local Unix documentation for restrictions or additional supported directives. If string cannot be parsed according to format, ValueError is raised. Values which are not provided as part of the input string are filled in with default values; the specific values are platform-dependent as the XPG standard does not provide sufficient information to constrain the result.
Note: This function relies entirely on the underlying platform's C library for the date parsing, and some of these libraries are buggy. There's nothing to be done about this short of a new, portable implementation of strptime().
Availability: Most modern Unix systems.
%Zis now deprecated, but the
%zescape that expands to the preferred hour/minute offset is not supported by all ANSI C libraries. Also, a strict reading of the original 1982 RFC 822 standard calls for a two-digit year (%y rather than %Y), but practice moved to 4-digit years long before the year 2000. The 4-digit year has been mandated by RFC 2822, which obsoletes RFC 822.