This module provides various time-related functions. It is always available, but not all functions are available on all platforms. Most of the functions defined in this module call platform C library functions with the same name. It may sometimes be helpful to consult the platform documentation, because the semantics of these functions varies among 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.
||tm_year||(for example, 1993)|
||tm_sec||range [0,61]; see (1) in strftime() description|
||tm_wday||range [0,6], Monday is 0|
||tm_isdst||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 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.
Changed in version 2.2: The time value sequence was changed from a tuple to a struct_time, with the addition of attribute names for the fields.
The module defines the following functions and data items:
'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.
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.
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.
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, 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.
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 Monday 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 (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(). If string cannot be parsed according to format, ValueError is raised. If the string to be parsed has excess data after parsing, ValueError is raised. The default values used to fill in any missing data is
(1900, 1, 1, 0, 0, 0, 0, 1, -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
The TZ environment variable should contain no whitespace.
The standard format of the TZ environment variable is: (whitespace added for clarity)
time has the same format as offset except that no leading sign ('-' or '+') is allowed. The default, if time is not given, is 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'
On many Unix systems (including *BSD, Linux, Solaris, and Darwin), it
is more convenient to use the system's zoneinfo (tzfile(5))
database to specify the timezone rules. To do this, set the
TZ environment variable to the path of the required timezone
datafile, relative to the root of the systems 'zoneinfo' timezone database,
usually located at /usr/share/zoneinfo. For example,
>>> os.environ['TZ'] = 'US/Eastern' >>> time.tzset() >>> time.tzname ('EST', 'EDT') >>> os.environ['TZ'] = 'Egypt' >>> time.tzset() >>> time.tzname ('EET', 'EEST')
%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.