Section 12.1. The time Module

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 typical cut-off points, a limitation that datetime and mx.DateTime let 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, called a time-tuple. (Time-tuples are covered in Table 12-1.) All items are integers: time-tuples don't keep track of fractions of a second. A time-tuple is an instance of struct_time. You can use it as a tuple, and access the items as read-only attributes x.tm_year, x.tm_mon, and so on, with the attribute names listed in Table 12-1. Wherever a function requires a time-tuple argument, you can pass an instance of struct_time or any other sequence whose items are nine integers in the right 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	112	1 is January; 12 is December.
2	Day	tm_mday	131
3	Hour	tm_hour	023	0 is midnight; 12 is noon.
4	Minute	tm_min	059
5	Second	tm_sec	061	60 and 61 for leap seconds.
6	Weekday	tm_wday	06	0 is Monday; 6 is Sunday.
7	Year day	tm_yday	1366	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 DST.

Module time supplies the following functions and attributes.

asctime

asctime([tupletime])

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

clock

clock( )

Returns the current CPU time as a floating-point number of seconds. To measure computational costs of different approaches, the value of time.clock is more useful than that of time.time (standard library module timeit, covered in "Module timeit" on page 484, is even better). On Unix-like platforms, the reason is that time.clock, using CPU time rather than elapsed time, is less dependent than 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

ctime([secs])

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

gmtime

gmtime([secs])

Accepts an instant expressed in seconds since the epoch and returns a time-tuple t with the UTC time (t.tm_isdst is always 0). gmtime( ) without arguments is like gmtime(time( )) (returns the time-tuple for the current time instant).

localtime

localtime([secs])

Accepts an instant expressed in seconds since the epoch and returns a time-tuple t with the local time (t.tm_isdst is 0 or 1, depending on whether DST applies to instant secs by local rules). localtime( ) without arguments is like localtime(time( )) (returns the time-tuple for the current time instant).

mktime

mktime(tupletime)

Accepts an instant expressed as a time-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 DST, or to -1 to let mktime compute whether DST is in effect at the given instant.

sleep

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 it's the main thread and some signal wakes it up) or after a longer suspension (depending on system scheduling of processes and threads).

strftime

strftime(fmt[,tupletime])

Accepts an instant expressed as a time-tuple in local time and returns a string representing the instant as specified by string fmt. If you omit tupletime, strftime uses localtime(time( )) (formats the current time instant in the local time zone). The syntax of string format is similar to the syntax specified in "String Formatting" on page 193. Conversion characters are different, as shown in Table 12-2. Refer to the time instant specified by tupletime; also, you can't specify width and precision in the format.

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	A.M. or P.M. 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 %%

For example, you can obtain dates just 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

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. The format string is like the one for strftime, covered in strftime on page 304.

time

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.

timezone

Attribute time.timezone is the offset in seconds of the local time zone (without DST) from UTC (>0 in the Americas; <=0 in most of Europe, Asia, Africa).

tzname

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