12.1 The time Module

The underlying C library determines the range of dates that the time module can handle. On Unix systems, years 1970 and 2038 are the typical cut-off points, a limitation that mx.DateTime lets you avoid. Time instants are normally specified in UTC (Coordinated Universal Time, once known as GMT, or Greenwich Mean Time). Module time also supports local time zones and Daylight Saving Time (DST), but only to the extent that support is supplied by the underlying C system library.

As an alternative to seconds since the epoch, a time instant can be represented by a tuple of nine integers known as a time-tuple. Items in time-tuples are covered in Table 12-1. All items are integers, and therefore time-tuples cannot keep track of fractions of a second. In Python 2.2 and later, the result of any function in module time that used to return a time-tuple is now of type struct_time. You can still use the result as a tuple, but you can also access the items as read-only attributes x.tm_year, x.tm_mon, and so on, using the attribute names listed in Table 12-1. Wherever a function used to require a time-tuple argument, you can now pass an instance of struct_time or any other sequence whose items are nine integers in the applicable ranges.

Table 12-1. Tuple form of time representation

Item	Meaning	Field name	Range	Notes
0	Year	tm_year	1970-2038	Wider on some platforms
1	Month	tm_mon	1-12	1 is January; 12 is December
2	Day	tm_mday	1-31
3	Hour	tm_hour	0-23	0 is midnight; 12 is noon
4	Minute	tm_min	0-59
5	Second	tm_sec	0-61	60 and 61 for leap seconds
6	Weekday	tm_wday	0-6	0 is Monday; 6 is Sunday
7	Year day	tm_yday	1-366	Day number within the year
8	DST flag	tm_isdst	-1 to 1	-1 means library determines DST

To translate a time instant from "a seconds since the epoch" floating-point value into a time-tuple, pass the floating-point value to a function (e.g., localtime) that returns a time-tuple with all nine items valid. When you convert in the other direction, mktime ignores items six (tm_wday) and seven (tm_yday) of the tuple. In this case, you normally set item eight (tm_isdst) to -1, so that mktime itself determines whether to apply Daylight Saving Time (DST).

Module time supplies the following functions and attributes.

asctime([tupletime])

Accepts a time-tuple and returns a 24-character string such as 'Tue Dec 10 18:07:14 2002'. asctime( ) without arguments is like asctime(localtime(time( ))) (i.e., it formats the current time instant).

clock(  )

Returns the current CPU time as a floating-point number of seconds. To measure computational costs of different approaches, it is generally better to use the results of time.clock rather than those of time.time. On Unix-like platforms, the reason is that the results of time.clock, using CPU time rather than elapsed time, are less dependent than those of time.time on unpredictable factors due to machine load. On Windows, this reason does not apply, as Windows has no concept of CPU time, but there is another reason: time.clock uses the higher-precision performance counter machine clock. The epoch (the time corresponding to a 0.0 result from time.clock) is arbitrary, but differences between the results of successive calls to time.clock in the same process are accurate.

ctime([secs])

Like asctime(localtime(secs)) (i.e., accepts an instant expressed in seconds since the epoch and returns a 24-character string form of that time instant). ctime( ) without arguments is like asctime(localtime(time( ))) (i.e., it formats the current time instant).

gmtime([secs])

Accepts an instant expressed in seconds since the epoch and returns a nine-item time-tuple t with the UTC time (DST, the last item of t, is always 0). gmtime( ) without arguments is like gmtime(time( )) (i.e., it returns the nine-item time-tuple for the current time instant).

localtime([secs])

Accepts an instant expressed in seconds since the epoch and returns a nine-item tuple t with the local time (DST, the last item of t, is set to 0 or 1, depending on whether DST applies to instant secs according to local rules). localtime( ) without arguments is like localtime(time( )) (i.e., it returns the nine-item time-tuple for the current time instant).

mktime(tupletime)

Accepts an instant expressed as a nine-item tuple in local time and returns a floating-point value with the instant expressed in seconds since the epoch. DST, the last item in tupletime, is meaningful: set it to 0 to get solar time, to 1 to get Daylight Saving Time, or to -1 to let mktime compute whether DST is in effect or not at the given instant.

sleep(secs)

Suspends the calling thread for secs seconds (secs is a floating-point number and can indicate a fraction of a second). The calling thread may start executing again before secs seconds (if some signal wakes it up) or after a longer suspension (depending on system scheduling of processes and threads).

strftime(fmt[,tupletime])

Accepts an instant expressed as a nine-item tuple in local time and returns a string that represents tupletime as specified by string fmt. If you omit tupletime, strftime uses localtime(time( )) instead (i.e., it formats the current time instant in the local time zone). The syntax of string format is similar to the syntax specified in Section 9.3. However, conversion characters are different, as shown in Table 12-2, and refer to the time instant specified by tupletime. Specifying width and precision explicitly works on some platforms, but not on all.

Table 12-2. Conversion characters for strftime

Type char	Meaning	Special notes
a	Weekday name, abbreviated	Depends on locale
A	Weekday name, full	Depends on locale
b	Month name, abbreviated	Depends on locale
B	Month name, full	Depends on locale
c	Complete date and time representation	Depends on locale
d	Day of the month	Between 1 and 31
H	Hour (24-hour clock)	Between 0 and 23
I	Hour (12-hour clock)	Between 1 and 12
j	Day of the year	Between 1 and 366
m	Month number	Between 1 and 12
M	Minute number	Between 0 and 59
p	`AM' or `PM' equivalent	Depends on locale
S	Second number	Between 0 and 61
U	Week number (Sunday first weekday)	Between 0 and 53
w	Weekday number	0 is Sunday, up to 6
W	Week number (Monday first weekday)	Between 0 and 53
x	Complete date representation	Depends on locale
X	Complete time representation	Depends on locale
y	Year number within century	Between 0 and 99
Y	Year number	1970 to 2038, or wider
Z	Name of time zone	Empty if no time zone exists
%	A literal % character	Encoded as %%

You can obtain dates as formatted by asctime (e.g., 'Tue Dec 10 18:07:14 2002') with the format string:

'%a %b %d %H:%M:%S %Y'

You can obtain dates compliant with RFC 822 (e.g., 'Tue, 10 Dec 2002 18:07:14 EST') with the format string:

'%a, %d %b %Y %H:%M:%S %Z'

strptime(str,fmt='%a %b %d %H:%M:%S %Y')

Parses str according to format string fmt, and returns the instant in time-tuple format. With Python 2.2 and earlier, strptime is not available on all platforms. However, a pure Python implementation is available at http://aspn.activestate.com/ASPN/Python/Cookbook/Recipe/56036. In Python 2.3, the pure Python implementation will be used as a fallback on platforms that provide no other, so that time.strptime will always be available.

time(  )

Returns the current time instant, a floating-point number of seconds since the epoch. On some platforms, the precision of time measurements is as low as one second.

Attribute time.timezone is the offset in seconds of the local time zone (without DST) from UTC (greater than 0 in the Americas and less than 0 in most of Europe, Asia, and Africa).

Attribute time.tzname is a pair of locale-dependent strings, the names of the local time zone without and with DST, respectively.