The Epoch

You learned in the previous section that you can manage Python time with a floating point number representing elapsed time since the beginning of an era.

Merriam-Webster defines an era as:

• A fixed point in time from which a series of years is reckoned
• A system of chronological notation computed from a given date as basis

The important concept to grasp here is that, when dealing with Python time, you’re considering a period of time identified by a starting point. In computing, you call this starting point theepoch.

The epoch, then, is the starting point against which you can measure the passage of time.

For example, if you define the epoch to be midnight on January 1, 1970 UTC—the epoch as defined on Windows and most UNIX systems—then you can represent midnight on January 2, 1970 UTC as86400 seconds since the epoch.

This is because there are 60 seconds in a minute, 60 minutes in an hour, and 24 hours in a day. January 2, 1970 UTC is only one day after the epoch, so you can apply basic math to arrive at that result:

>>>60*60*2486400

It is also important to note that you can still represent time before the epoch. The number of seconds would just be negative.

For example, you would represent midnight on December 31, 1969 UTC (using an epoch of January 1, 1970) as-86400 seconds.

While January 1, 1970 UTC is a common epoch, it is not the only epoch used in computing. In fact, different operating systems, filesystems, and APIs sometimes use different epochs.

As you saw before, UNIX systems define the epoch as January 1, 1970. The Win32 API, on the other hand, defines the epoch asJanuary 1, 1601.

You can usetime.gmtime() to determine your system’s epoch:

>>>importtime>>>time.gmtime(0)time.struct_time(tm_year=1970, tm_mon=1, tm_mday=1, tm_hour=0, tm_min=0, tm_sec=0, tm_wday=3, tm_yday=1, tm_isdst=0)

You’ll learn aboutgmtime() andstruct_time throughout the course of this article. For now, just know that you can usetime to discover the epoch using this function.

Now that you understand more about how to measure time in seconds using an epoch, let’s take a look at Python’stime module to see what functions it offers that help you do so.

Python Time in Seconds as a Floating Point Number

First,time.time() returns the number of seconds that have passed since the epoch. The return value is a floating point number to account for fractional seconds:

>>>fromtimeimporttime>>>time()1551143536.9323719

The number you get on your machine may be very different because the reference point considered to be the epoch may be very different.

Measuring time in seconds is useful for a number of reasons:

• You can use a float to calculate the difference between two points in time.
• A float is easilyserializable, meaning that it can be stored for data transfer and come out intact on the other side.

Sometimes, however, you may want to see thecurrent time represented as a string. To do so, you can pass the number of seconds you get fromtime() intotime.ctime().

Python Time in Seconds as a String Representing Local Time

As you saw before, you may want to convert the Python time, represented as the number of elapsed seconds since the epoch, to astring. You can do so usingctime():

>>>fromtimeimporttime,ctime>>>t=time()>>>ctime(t)'Mon Feb 25 19:11:59 2019'

Here, you’ve recorded the current time in seconds into thevariablet, then passedt as an argument toctime(), which returns a string representation of that same time.

>>>fromtimeimportctime>>>ctime()'Mon Feb 25 19:11:59 2019'

The string representation of time, also known as atimestamp, returned byctime() is formatted with the following structure:

1. Day of the week:Mon (Monday)
2. Month of the year:Feb (February)
3. Day of the month:25
4. Hours, minutes, and seconds using the24-hour clock notation:19:11:59
5. Year:2019

The previous example displays the timestamp of a particular moment captured from a computer in the South Central region of the United States. But, let’s say you live in Sydney, Australia, and you executed the same command at the same instant.

Instead of the above output, you’d see the following:

>>>fromtimeimporttime,ctime>>>t=time()>>>ctime(t)'Tue Feb 26 12:11:59 2019'

Notice that theday of week,day of month, andhour portions of the timestamp are different than the first example.

These outputs are different because the timestamp returned byctime() depends on your geographical location.

The representation of time dependent on your physical location is calledlocal time and makes use of a concept calledtime zones.

Let’s dig a little deeper into the notion of time zones so that you can better understand Python time representations.

UTC and Time Zones

UTC is the time standard against which all the world’s timekeeping is synchronized (or coordinated). It is not, itself, a time zone but rather a transcendent standard that defines what time zones are.

UTC time is precisely measured usingastronomical time, referring to the Earth’s rotation, andatomic clocks.

Time zones are then defined by their offset from UTC. For example, in North and South America, the Central Time Zone (CT) is behind UTC by five or six hours and, therefore, uses the notation UTC-5:00 or UTC-6:00.

Sydney, Australia, on the other hand, belongs to the Australian Eastern Time Zone (AET), which is ten or eleven hours ahead of UTC (UTC+10:00 or UTC+11:00).

This difference (UTC-6:00 to UTC+10:00) is the reason for the variance you observed in the two outputs fromctime() in the previous examples:

• Central Time (CT):'Mon Feb 25 19:11:59 2019'
• Australian Eastern Time (AET):'Tue Feb 26 12:11:59 2019'

These times are exactly sixteen hours apart, which is consistent with the time zone offsets mentioned above.

You may be wondering why CT can be either five or six hours behind UTC or why AET can be ten or eleven hours ahead. The reason for this is that some areas around the world, including parts of these time zones, observe daylight savings time.

Daylight Savings Time

Summer months generally experience moredaylight hours than winter months. Because of this, some areas observe daylight savings time (DST) during the spring and summer to make better use of those daylight hours.

For places that observe DST, their clocks will jump ahead one hour at the beginning of spring (effectively losing an hour). Then, in the fall, the clocks will be reset to standard time.

The letters S and D represent standard time and daylight savings time in time zone notation:

• Central Standard Time (CST)
• Australian Eastern Daylight Time (AEDT)

When you represent times as timestamps in local time, it is always important to consider whether DST is applicable or not.

ctime() accounts for daylight savings time. So, the output difference listed previously would be more accurate as the following:

• Central Standard Time (CST):'Mon Feb 25 19:11:59 2019'
• Australian Eastern Daylight Time (AEDT):'Tue Feb 26 12:11:59 2019'

Python Time as a Tuple

Instead of using a number to represent Python time, you can use another primitive data structure: atuple.

The tuple allows you to manage time a little more easily by abstracting some of the data and making it more readable.

When you represent time as a tuple, each element in your tuple corresponds to a specific element of time:

1. Year
2. Month as an integer, ranging between 1 (January) and 12 (December)
3. Day of the month
4. Hour as an integer, ranging between 0 (12 A.M.) and 23 (11 P.M.)
5. Minute
6. Second
7. Day of the week as an integer, ranging between 0 (Monday) and 6 (Sunday)
8. Day of the year
9. Daylight savings time as an integer with the following values:
   • 1 is daylight savings time.
   • 0 is standard time.
   • -1 is unknown.

Using the methods you’ve already learned, you can represent the same Python time in two different ways:

>>>fromtimeimporttime,ctime>>>t=time()>>>t1551186415.360564>>>ctime(t)'Tue Feb 26 07:06:55 2019'>>>time_tuple=(2019,2,26,7,6,55,1,57,0)

In this case, botht andtime_tuple represent the same time, but the tuple provides a more readable interface for working with time components.

While the tuple provides a more manageable interface for working with Python time, there is an even better object:struct_time.

Python Time as an Object

The problem with the tuple construct is that it still looks like a bunch of numbers, even though it’s better organized than a single, seconds-based number.

struct_time provides a solution to this by utilizingNamedTuple, from Python’scollections module, to associate the tuple’s sequence of numbers with useful identifiers:

>>>fromtimeimportstruct_time>>>time_tuple=(2019,2,26,7,6,55,1,57,0)>>>time_obj=struct_time(time_tuple)>>>time_objtime.struct_time(tm_year=2019, tm_mon=2, tm_mday=26, tm_hour=7, tm_min=6, tm_sec=55, tm_wday=1, tm_yday=57, tm_isdst=0)

Now, you can access specific elements oftime_obj using the attribute’s name rather than an index:

>>>day_of_year=time_obj.tm_yday>>>day_of_year57>>>day_of_month=time_obj.tm_mday>>>day_of_month26

Beyond the readability and usability ofstruct_time, it is also important to know because it is the return type of many of the functions in the Pythontime module.

Coordinated Universal Time (UTC)

The epoch uses UTC for its definition rather than a time zone. Therefore, the seconds elapsed since the epoch is not variable depending on your geographical location.

However, the same cannot be said ofstruct_time. The object representation of Python time may or may not take your time zone into account.

There are two ways to convert a float representing seconds to astruct_time:

1. UTC
2. Local time

To convert a Python time float to a UTC-basedstruct_time, the Pythontime module provides a function calledgmtime().

You’ve seengmtime() used once before in this article:

>>>importtime>>>time.gmtime(0)time.struct_time(tm_year=1970, tm_mon=1, tm_mday=1, tm_hour=0, tm_min=0, tm_sec=0, tm_wday=3, tm_yday=1, tm_isdst=0)

You used this call to discover your system’s epoch. Now, you have a better foundation for understanding what’s actually happening here.

gmtime() converts the number of elapsed seconds since the epoch to astruct_time in UTC. In this case, you’ve passed0 as the number of seconds, meaning you’re trying to find the epoch, itself, in UTC.

As you saw before,struct_time cannot represent fractional seconds, sogmtime() ignores the fractional seconds in the argument:

>>>importtime>>>time.gmtime(1.99)time.struct_time(tm_year=1970, tm_mon=1, tm_mday=1, tm_hour=0, tm_min=0, tm_sec=1, tm_wday=3, tm_yday=1, tm_isdst=0)

Notice that even though the number of seconds you passed was very close to2, the.99 fractional seconds were simply ignored, as shown bytm_sec=1.

Thesecs parameter forgmtime() is optional, meaning you can callgmtime() with no arguments. Doing so will provide the current time in UTC:

>>>importtime>>>time.gmtime()time.struct_time(tm_year=2019, tm_mon=2, tm_mday=28, tm_hour=12, tm_min=57, tm_sec=24, tm_wday=3, tm_yday=59, tm_isdst=0)

Interestingly, there is no inverse for this function withintime. Instead, you’ll have to look in Python’scalendar module for a function namedtimegm():

>>>importcalendar>>>importtime>>>time.gmtime()time.struct_time(tm_year=2019, tm_mon=2, tm_mday=28, tm_hour=13, tm_min=23, tm_sec=12, tm_wday=3, tm_yday=59, tm_isdst=0)>>>calendar.timegm(time.gmtime())1551360204

timegm() takes a tuple (orstruct_time, since it is a subclass of tuple) and returns the corresponding number of seconds since the epoch.

Working with UTC is valuable in programming because it’s a standard. You don’t have to worry about DST, time zone, or locale information.

That said, there are plenty of cases when you’d want to use local time. Next, you’ll see how to convert from seconds to local time so that you can do just that.

Local Time

In your application, you may need to work with local time rather than UTC. Python’stime module provides a function for getting local time from the number of seconds elapsed since the epoch calledlocaltime().

The signature oflocaltime() is similar togmtime() in that it takes an optionalsecs argument, which it uses to build astruct_time using your local time zone:

>>>importtime>>>time.time()1551448206.86196>>>time.localtime(1551448206.86196)time.struct_time(tm_year=2019, tm_mon=3, tm_mday=1, tm_hour=7, tm_min=50, tm_sec=6, tm_wday=4, tm_yday=60, tm_isdst=0)

Notice thattm_isdst=0. Since DST matters with local time,tm_isdst will change between0 and1 depending on whether or not DST is applicable for the given time. Sincetm_isdst=0, DST is not applicable for March 1, 2019.

In the United States in 2019, daylight savings time begins on March 10. So, to test if the DST flag will change correctly, you need to add 9 days’ worth of seconds to thesecs argument.

To compute this, you take the number of seconds in a day (86,400) and multiply that by 9 days:

>>>new_secs=1551448206.86196+(86400*9)>>>time.localtime(new_secs)time.struct_time(tm_year=2019, tm_mon=3, tm_mday=10, tm_hour=8, tm_min=50, tm_sec=6, tm_wday=6, tm_yday=69, tm_isdst=1)

Now, you’ll see that thestruct_time shows the date to be March 10, 2019 withtm_isdst=1. Also, notice thattm_hour has also jumped ahead, to8 instead of7 in the previous example, because of daylight savings time.

Since Python 3.3,struct_time has also included two attributes that are useful in determining the time zone of thestruct_time:

1. tm_zone
2. tm_gmtoff

At first, these attributes were platform dependent, but they have been available on all platforms since Python 3.6.

First,tm_zone stores the local time zone:

>>>importtime>>>current_local=time.localtime()>>>current_local.tm_zone'CST'

Here, you can see thatlocaltime() returns astruct_time with the time zone set toCST (Central Standard Time).

As you saw before, you can also tell the time zone based on two pieces of information, the UTC offset and DST (if applicable):

>>>importtime>>>current_local=time.localtime()>>>current_local.tm_gmtoff-21600>>>current_local.tm_isdst0

In this case, you can see thatcurrent_local is21600 seconds behind GMT, which stands for Greenwich Mean Time. GMT is the time zone with no UTC offset: UTC±00:00.

21600 seconds divided by seconds per hour (3,600) means thatcurrent_local time isGMT-06:00 (orUTC-06:00).

You can use the GMT offset plus the DST status to deduce thatcurrent_local isUTC-06:00 at standard time, which corresponds to the Central standard time zone.

Likegmtime(), you can ignore thesecs argument when callinglocaltime(), and it will return the current local time in astruct_time:

>>>importtime>>>time.localtime()time.struct_time(tm_year=2019, tm_mon=3, tm_mday=1, tm_hour=8, tm_min=34, tm_sec=28, tm_wday=4, tm_yday=60, tm_isdst=0)

Unlikegmtime(), the inverse function oflocaltime() does exist in the Pythontime module. Let’s take a look at how that works.

asctime()

You useasctime() for converting a time tuple orstruct_time to a timestamp:

>>>importtime>>>time.asctime(time.gmtime())'Fri Mar  1 18:42:08 2019'>>>time.asctime(time.localtime())'Fri Mar  1 12:42:15 2019'

Bothgmtime() andlocaltime() returnstruct_time instances, for UTC and local time respectively.

You can useasctime() to convert eitherstruct_time to a timestamp.asctime() works similarly toctime(), which you learned about earlier in this article, except instead of passing a floating point number, you pass a tuple. Even the timestamp format is the same between the two functions.

As withctime(), the parameter forasctime() is optional. If you do not pass a time object toasctime(), then it will use the current local time:

>>>importtime>>>time.asctime()'Fri Mar  1 12:56:07 2019'

As withctime(), it also ignores locale information.

One of the biggest drawbacks ofasctime() is its format inflexibility.strftime() solves this problem by allowing you to format your timestamps.

strftime()

You may find yourself in a position where the string format fromctime() andasctime() isn’t satisfactory for your application. Instead, you may want to format your strings in a way that’s more meaningful to your users.

One example of this is if you would like to display your time in a string that takes locale information into account.

To format strings, given astruct_time or Python time tuple, you usestrftime(), which stands for “stringformat time.”

strftime() takes two arguments:

1. format specifies the order and form of the time elements in your string.
2. t is an optional time tuple.

To format a string, you usedirectives. Directives are character sequences that begin with a% that specify a particular time element, such as:

• %d: Day of the month
• %m: Month of the year
• %Y: Year

For example, you can output the date in your local time using theISO 8601 standard like this:

>>>importtime>>>time.strftime('%Y-%m-%d',time.localtime())'2019-03-01'

>>>fromdatetimeimportdate>>>date(year=2019,month=3,day=1).isoformat()'2019-03-01'

As you saw before, a great benefit of usingstrftime() overasctime() is its ability to render timestamps that make use of locale-specific information.

For example, if you want to represent the date and time in a locale-sensitive way, you can’t useasctime():

>>>fromtimeimportasctime>>>asctime()'Sat Mar  2 15:21:14 2019'>>>importlocale>>>locale.setlocale(locale.LC_TIME,'zh_HK')# Chinese - Hong Kong'zh_HK'>>>asctime()'Sat Mar  2 15:58:49 2019'

Notice that even after programmatically changing your locale,asctime() still returns the date and time in the same format as before.

When you usestrftime(), however, you’ll see that it accounts for locale:

>>>fromtimeimportstrftime,localtime>>>strftime('%c',localtime())'Sat Mar  2 15:23:20 2019'>>>importlocale>>>locale.setlocale(locale.LC_TIME,'zh_HK')# Chinese - Hong Kong'zh_HK'>>>strftime('%c',localtime())'六  3/ 2 15:58:12 2019' 2019'

Here, you have successfully utilized the locale information because you usedstrftime().

If the time tuple is not passed to the parametert, thenstrftime() will use the result oflocaltime() by default. So, you could simplify the examples above by removing the optional second argument:

>>>fromtimeimportstrftime>>>strftime('The current local datetime is:%c')'The current local datetime is: Fri Mar  1 23:18:32 2019'

Here, you’ve used the default time instead of passing your own as an argument. Also, notice that theformat argument can consist of text other than formatting directives.

The Pythontime module also includes the inverse operation of converting a timestamp back into astruct_time object.