Python 3 time module
Last updated on July 27, 2020
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:
1 2 3 | >>>
>>> import time
>>>
|
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.
1 2 3 4 | >>>
>>> time.time()
1531326753.9201949
>>>
|
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 | >>>
>>> lt1 = time.localtime(1200000000) # convert the timestamp 1200000000 to local time
>>> lt1
time.struct_time(tm_year=2008, tm_mon=1, tm_mday=11, tm_hour=2,
tm_min=50, tm_sec=0, tm_wday=4, tm_yday=11, tm_isdst=0)
>>>
>>>
>>> lt2 = time.localtime() # convert timestamp returned by time() to local time
>>> lt2
time.struct_time(tm_year=2018, tm_mon=7, tm_mday=11, tm_hour=22,
tm_min=3, tm_sec=3, tm_wday=2, tm_yday=192, tm_isdst=0)
>>>
>>>
|
Once you have access to timetuple you can access values inside it either by index or attribute name. For example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | >>>
>>>
>>> lt2.tm_year, lt2.tm_mon, lt2.tm_mday
(2018, 7, 12)
>>>
>>>
>>> lt2[0], lt2[1], lt2[2] # same as: lt2.tm_year, lt2.tm_mon, lt2.tm_mday
(2018, 7, 12)
>>>
>>>
>>> lt2.tm_hour, lt2.tm_min, lt2.tm_sec
(0, 3, 40)
>>>
>>>
>>> lt2[3], lt2[4], lt2[5] # same as: lt2.tm_hour, lt2.tm_min, lt2.tm_sec
(0, 3, 40)
>>>
>>>
>>> lt2.tm_wday, lt2.tm_yday, lt2.tm_isdst
(3, 193, 0)
>>>
>>>
>>> lt2[6], lt2[7], lt2[8] # same as: lt2.tm_wday, lt2.tm_yday, lt2.tm_isdst
(3, 193, 0)
>>>
>>>
|
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | >>>
>>>
>>> gm1 = time.gmtime(1200000000) # convert timestamp 1200000000 to UTC time
>>> gm1
time.struct_time(tm_year=2008, tm_mon=1, tm_mday=10, tm_hour=21,
tm_min=20, tm_sec=0, tm_wday=3, tm_yday=10, tm_isdst=0)
>>>
>>>
>>> gm2 = time.gmtime() # convert timestamp returned by time() to UTC time
>>> gm2
time.struct_time(tm_year=2018, tm_mon=7, tm_mday=12, tm_hour=8,
tm_min=5, tm_sec=38, tm_wday=3, tm_yday=193, tm_isdst=0)
>>>
>>>
>>> gm2.tm_year, gm2.tm_mon, gm2.tm_mday, gm2.tm_hour, gm2.tm_min, gm2.tm_sec
(2018, 7, 12, 8, 22, 36)
>>>
>>>
>>> gm1[0], gm1[1], gm1[2], gm1[3], gm1[4], gm1[5]
(2008, 1, 10, 21, 20, 0)
>>>
>>>
|
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | >>>
>>>
>>> timestamp, timetuple = time.time(), time.localtime()
>>>
>>>
>>> timestamp, timetuple
(1531384941.615937, time.struct_time(tm_year=2018, tm_mon=7, tm_mday=12,
tm_hour=14, tm_min=12, tm_sec=21, tm_wday=3, tm_yday=193, tm_isdst=0))
>>>
>>>
>>> time.mktime(timetuple)
1531384941.0
>>>
>>>
|
sleep() function #
Syntax: sleep(seconds)
This function suspends the process execution for the specified number of seconds.
1 2 3 4 5 6 7 8 9 10 11 12 13 | >>>
>>>
>>> for i in range(5):
... time.sleep(5)
... print(time.time())
...
1531391820.9281697
1531391825.9332898
1531391830.9384072
1531391835.9435263
1531391840.9486341
>>>
>>>
|
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().
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | >>>
>>>
>>> time.ctime()
'Thu Jul 12 16:18:51 2018'
>>>
>>>
>>> time.ctime(None)
'Thu Jul 12 16:18:54 2018'
>>>
>>>
>>> time.ctime(1290000000)
'Wed Nov 17 18:50:00 2010'
>>>
>>>
|
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | >>>
>>>
>>> time.asctime()
'Thu Jul 12 16:57:53 2018'
>>>
>>>
>>> time.asctime(time.localtime()) # same as time.asctime()
'Thu Jul 12 16:58:03 2018'
>>>
>>>
>>> time.asctime(time.localtime(1230000000))
'Tue Dec 23 08:10:00 2008'
>>>
>>>
|
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 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | >>>
>>>
>>> time.strftime("%Y/%m/%d")
'2018/07/12'
>>>
>>>
>>> time.strftime("%H:%m:%d")
'18:07:12'
>>>
>>>
>>> time.strftime("%a %B %d %Y %H:%I:%S %p")
'Thu July 12 2018 18:06:46 PM'
>>>
>>>
>>> time.strftime("%x", time.localtime(1230000000))
'12/23/08'
>>>
>>>
>>> time.strftime("%X", time.localtime(1230000000))
'08:10:00'
>>>
>>>
|
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | >>>
>>>
>>> time.strptime(time.ctime())
time.struct_time(tm_year=2018, tm_mon=7, tm_mday=12, tm_hour=19,
tm_min=6, tm_sec=3, tm_wday=3, tm_yday=193, tm_isdst=-1)
>>>
>>>
>>> time.strptime('11-01-2018', "%d-%m-%Y")
time.struct_time(tm_year=2018, tm_mon=1, tm_mday=11, tm_hour=0,
tm_min=0, tm_sec=0, tm_wday=3, tm_yday=11, tm_isdst=-1)
>>>
>>>
>>> time.strptime('Mon, 01 Dec 2018', "%a, %m %b %Y")
time.struct_time(tm_year=2018, tm_mon=1, tm_mday=1, tm_hour=0,
tm_min=0, tm_sec=0, tm_wday=0, tm_yday=1, tm_isdst=-1)
>>>
>>>
>>> time.strptime('01-Dec-2018', "%m-%b-%Y")
time.struct_time(tm_year=2018, tm_mon=1, tm_mday=1, tm_hour=0,
tm_min=0, tm_sec=0, tm_wday=0, tm_yday=1, tm_isdst=-1)
>>>
>>>
>>> time.strptime('01-Dec-2018', "%m-%b-%y") # string and format do not match, thus ValueError is raised
...
ValueError: unconverted data remains: 18
>>>
>>>
|
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).
1 2 3 4 5 6 | >>>
>>>
>>> time.tzname
('SGT', 'SGT')
>>>
>>>
|
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.
1 2 3 4 5 6 7 8 9 10 | >>>
>>>
>>> time.timezone
-28800
>>>
>>>
>>> time.timezone/3600 # difference between UTC time and localtime in hours
-8.0
>>>
>>>
|
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | >>>
>>>
>>> time.tzname # initial time zone
('SGT', 'SGT')
>>>
>>>
>>> import os
>>> os.environ['TZ'] = 'Europe/Moscow'
>>>
>>>
>>> time.tzset() # change time zone
>>>
>>> time.tzname # local time zone is now changed to Moscow
('MSK', 'MSK')
>>>
>>>
|
My default time zone is changed for the session. If you now call the localtime() function, it will return the local time of Moscow.
1 2 3 4 5 6 7 | >>>
>>>
>>> time.localtime()
time.struct_time(tm_year=2018, tm_mon=7, tm_mday=12, tm_hour=20,
tm_min=0, tm_sec=27, tm_wday=3, tm_yday=193, tm_isdst=0)
>>>
>>>
|
Load Comments