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

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

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

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

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

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

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

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

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

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

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 (greater than 0 in the Americas and less than 0 in most of Europe, Asia, and Africa).

tzname

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



    Part III: Python Library and Extension Modules