Python 3 time module

The time module provides a number of time-related functions. Most of the functions found in this module call the platform C library functions behind the scenes with the same name.

To import the time module enter the following command:

Unix Epoch Time

Most modern computers store dates and times as a difference of seconds between January 1, 1970 00:00:00 UTC and the time to be stored (also in UTC). We call this difference Unix timestamp or Unix epoch time or simply timestamp. For example, date and time “11 July 2018 22:52:42” in UTC can be represented as timestamp 1531329762.

In the following sections, we discuss some common attributes and functions of the time module.

time() function

Syntax: time() -> floating point number

The time() function returns the number of seconds passed since January 1, 1970 00:00:00 UTC as a floating point number.

localtime() function

Syntax: localtime([seconds]) -> (tm_year,tm_mon,tm_mday,tm_hour,tm_min,
tm_sec,tm_wday,tm_yday,tm_isdst)

Converts the specified Unix timestamp to local time. If the seconds argument not passed in, it uses timestamp returned by the time() function. This function returns a time.struct_time object with the following attributes.

Attribute Description
tm_year year
tm_mon month of year (1-12)
tm_mday day of month (1-31)
tm_hour hour (1-23)
tm_min minutes (0-59)
tm_sec seconds (0-59)
tm_wday day of week (0-6) (Sunday = 0, Monday = 1 and so on)
tm_yday day of year (0-365), also known as julian day
tm_isday daylight saving flag (0, 1 or -1). A value of 1 indicates that the daylight savings is in effect, 0 if daylight savings is not in effect and -1 if the information is not available.

The time.struct_time object is also commonly known as timetuple.

Once you have access to timetuple you can access values inside it either by index or attribute name. For example:

gmtime() function

Syntax: gmtime([seconds]) -> (tm_year,tm_mon,tm_mday,tm_hour,tm_min,
tm_sec,tm_wday,tm_yday,tm_isdst)

Works exactly like localtime() but the converts the specified timestamp to UTC instead of local time. If the seconds argument not passed in, it uses timestamp returned by the time() function.

mktime() function

Syntax: mktime(timetuple) -> floating point number

This is the opposite of localtime() function. It accepts a timetuple representing local time and returns the number of seconds passed since January 1, 1970 00:00:00 UTC.

sleep() function

Syntax: sleep(seconds)

This function suspends the process execution for the specified number of seconds.

If you run the preceding code interactively, you will find that the for loop prints the timestamp after every 5 seconds.

ctime() function

Syntax: ctime([seconds]) -> string

Converts the timestamp to a string representation in local time. If seconds argument not specified or None, it uses timestamp returned by time().

asctime() function

Syntax: asctime([timetuple]) -> string

Converts the specified timetuple to a string representation in local time. If the timetuple is not specified, it uses current time returned by the localtime() function.

strftime() function

Syntax: strftime(format[, timetuple]) -> string

The strftime() function converts the timetuple to a string representation. It takes two arguments, format and an optional timetuple, and returns string according to the format codes used in the first argument. If timetuple not specified, it uses current time returned by the localtime() function.

The following table lists some common format codes:

Format Code Description
%d Day of the month
%H hours in 12-hour format
%I hours in 24-hour format
%M minutes
%S seconds
%p A.M. or P.M. (depends upon locale)
%m month number
%w weekday
%y 2 digit year
%Y 4 digit year
%Z Timezone name
%x Date representation according to locale
%X Time representation according to locale
%b Locale’s abbreviated month name
%B Locale’s full month name
%a Locale’s abbreviated weekday name

strptime() function

Syntax: strptime(string, format) -> struct_time

The strptime() function lets you convert date string to a timetuple according to the format string format. By default, the format argument is set to '%a %b %d %H:%M:%S %Y'. This is the same format as produced by the ctime() function. If the string and format do not match it raises ValueError exception.

tzname attribute

The tzname attribute returns a tuple containing two values: name of the local time zone and name of the local daylight saving time zone (if defined).

As you can see, my default time zone is set to Asia/Singapore. To determine the offset between UTC and local time we use the timezone attribute.

timezone attribute

The timezone attribute returns the difference between the UTC time and local time in seconds.

This means that the Asia/Singapore time zone is 8 hours (or 28800 seconds) ahead of UTC.

tzset() function

The tzset() function changes the local time zone to the value stored in the TZ environment variable.

My default time zone is changed for the session. If you now call the localtime() function, it will return the local time of Moscow.

Leave a Comment