How Computers Count Time

Nearly all computers count time from an instant called theUnix epoch. This occurred on January 1, 1970, at 00:00:00 UTC. UTC stands forCoordinated Universal Time and refers to the time at a longitude of 0°. UTC is often also calledGreenwich Mean Time, or GMT. UTC is not adjusted for daylight saving time, so it consistently keeps twenty-four hours in every day.

By definition, Unix time elapses at the same rate as UTC, so a one-second step in UTC corresponds to a one-second step in Unix time. You can usually figure out the date and time in UTC of any given instant since January 1, 1970, by counting the number of seconds since the Unix epoch, with the exception ofleap seconds. Leap seconds are occasionally added to UTC to account for the slowing of the Earth’s rotation but are not added to Unix time.

Nearly all programming languages, includingPython, incorporate the concept of Unix time. Python’s standard library includes a module calledtime that can print the number of seconds since the Unix epoch:

>>>importtime>>>time.time()1579718137.550164

In this example, youimport thetime module and executetime() to print the Unix time, or number of seconds (excluding leap seconds) since the epoch.

In addition to Unix time, computers need a way to convey time information to users. As you saw in the last example, Unix time is nearly impossible for a human to parse. Instead, Unix time is typically converted to UTC, which can then be converted into a local time usingtime zone offsets.

TheInternet Assigned Numbers Authority (IANA) maintains adatabase of all of the values of time zone offsets. IANA also releases regular updates that include any changes in time zone offsets. This database is often included with your operating system, although certain applications may include an updated copy.

The database contains a copy of all the designated time zones and how many hours and minutes they’re offset from UTC. So, during the winter, when daylight saving time is not in effect, the US Eastern time zone has an offset of -05:00, or negative five hours from UTC. Other regions have different offsets, which may not be integer hours. The UTC offset for Nepal, for example, is +05:45, or positive five hours and forty-five minutes from UTC.

How Standard Dates Can Be Reported

Unix time is how computers count time, but it would be incredibly inefficient for humans to determine the time by calculating the number of seconds from an arbitrary date. Instead, we work in terms of years, months, days, and so forth. But even with these conventions in place, another layer of complexity stems from the fact that different languages and cultures have different ways of writing the date.

For instance, in the United States, dates are usually written starting with the month, then the day, then the year. This means that January 31, 2020, is written as01-31-2020. This closely matches the long-form written version of the date.

However, most of Europe and many other areas write the date starting with the day, then the month, then the year. This means that January 31, 2020, is written as31-01-2020. These differences can cause all sorts of confusion when communicating across cultures.

To help avoid communication mistakes, the International Organization for Standardization (ISO) developedISO 8601. This standard specifies that all dates should be written in order of most-to-least-significant data. This means the format is year, month, day, hour, minute, and second:

YYYY-MM-DD HH:MM:SS

In this example,YYYY represents a four-digit year, andMM andDD are the two-digit month and day, starting with a zero if necessary. After that,HH,MM, andSS represent the two-digit hours, minutes, and seconds, starting with a zero if necessary.

The advantage of this format is that the date can be represented with no ambiguity. Dates written asDD-MM-YYYY orMM-DD-YYYY can be misinterpreted if the day is a valid month number. You’ll see a littlelater on how you can use the ISO 8601 format with Pythondatetime.

How Time Should Be Stored in Your Program

Most developers who have worked with time have heard the advice to convert local time to UTC and store that value for later reference. In many cases, especially when you’re storing dates from the past, this is enough information to do any necessary arithmetic.

However, a problem can happen if a user of your program inputs a future date in their local time. Time zone and daylight saving time rules change fairly frequently, as you saw earlier with the 2007 change in daylight saving time for the United States and Canada. If the time zone rules for your user’s location change before the future date that they inputted, then UTC won’t provide enough information to convert back to the correct local time.

In this case, you need to store the local time, including the time zone, that the user inputted as well as the version of the IANA time zone database that was in effect when the user saved the time. This way, you’ll always be able to convert the local time to UTC. However, this approach won’t always allow you to convert UTC to the correct local time.

Creating Pythondatetime Instances

The three classes that represent dates and times indatetime have similarinitializers. They can beinstantiated by passing keyword arguments for each of the attributes, such asyear,date, orhour. You can try the code below to get a sense of how each object is created:

>>>fromdatetimeimportdate,time,datetime>>>date(year=2020,month=1,day=31)datetime.date(2020, 1, 31)>>>time(hour=13,minute=14,second=31)datetime.time(13, 14, 31)>>>datetime(year=2020,month=1,day=31,hour=13,minute=14,second=31)datetime.datetime(2020, 1, 31, 13, 14, 31)

In this code, youimport the three main classes fromdatetime andinstantiate each of them by passing arguments to the constructor. You can see that this code is somewhat verbose, and if you don’t have the information you need asintegers, these techniques can’t be used to createdatetime instances.

Fortunately,datetime provides several other convenient ways to createdatetime instances. These methods don’t require you to use integers to specify each attribute, but instead allow you to use some other information:

1. date.today() creates adatetime.date instance with the current local date.
2. datetime.now() creates adatetime.datetime instance with the current local date and time.
3. datetime.combine() combines instances ofdatetime.date anddatetime.time into a singledatetime.datetime instance.

These three ways of creatingdatetime instances are helpful when you don’t know in advance what information you need to pass into the basic initializers. You can try out this code to see how the alternate initializers work:

>>>fromdatetimeimportdate,time,datetime>>>today=date.today()>>>todaydatetime.date(2020, 1, 24)>>>now=datetime.now()>>>nowdatetime.datetime(2020, 1, 24, 14, 4, 57, 10015)>>>current_time=time(now.hour,now.minute,now.second)>>>datetime.combine(today,current_time)datetime.datetime(2020, 1, 24, 14, 4, 57)

In this code, you usedate.today(),datetime.now(), anddatetime.combine() to create instances ofdate,datetime, andtime objects. Each instance is stored in a differentvariable:

1. today is adate instance that has only the year, month, and day.
2. now is adatetime instance that has the year, month, day, hour, minute, second, and microseconds.
3. current_time is atime instance that has the hour, minute, and second set to the same values asnow.

On the last line, you combine the date information intoday with the time information incurrent_time to produce a newdatetime instance.

Using Strings to Create Pythondatetime Instances

Another way to createdate instances is to use.fromisoformat(). To use this method, you provide astring with the date in the ISO 8601 format that you learned aboutearlier. For instance, you might provide a string with the year, month, and date specified:

2020-01-31

This string represents the date January 31, 2020, according to the ISO 8601 format. You can create adate instance with the following example:

>>>fromdatetimeimportdate>>>date.fromisoformat("2020-01-31")datetime.date(2020, 1, 31)

In this code, you usedate.fromisoformat() to create adate instance for January 31, 2020. This method is very useful because it’s based on the ISO 8601 standard. But what if you have a string that represents a date and time but isn’t in the ISO 8601 format?

Fortunately, Pythondatetime provides a method called.strptime() to handle this situation. This method uses a specialmini-language to tell Python which parts of the string are associated with thedatetime attributes.

To construct adatetime from a string using.strptime(), you have to tell Python what each of the parts of the string represents using formatting codes from the mini-language. You can try this example to see how.strptime() works:

 1>>>date_string="01-31-2020 14:45:37" 2>>>format_string="%m-%d-%Y %H:%M:%S"

Online 1, you createdate_string, which represents the date and time January 31, 2020, at 2:45:37 PM. Online 2, you createformat_string, which uses the mini-language to specify how the parts ofdate_string will be turned intodatetime attributes.

Informat_string, you include several formatting codes and all of the dashes (-), colons (:), and spaces exactly as they appear indate_string. To process the date and time indate_string, you include the following formatting codes:

A complete listing of all of the options in the mini-language is outside the scope of this tutorial, but you can find several good references on the web, including in Python’sdocumentation and on a website calledstrftime.org.

Now thatdate_string andformat_string are defined, you can use them to create adatetime instance. Here’s an example of how.strptime() works:

 3>>>fromdatetimeimportdatetime 4>>>datetime.strptime(date_string,format_string) 5datetime.datetime(2020, 1, 31, 14, 45, 37)

In this code, you importdatetime online 3 and usedatetime.strptime() withdate_string andformat_string online 4. Finally,line 5 shows the values of the attributes in thedatetime instance created by.strptime(). You can see that they match the values shown in the table above.

 1>>>importdateparser 2>>>dateparser.parse("yesterday") 3datetime.datetime(2020, 3, 13, 14, 39, 1, 350918) 4>>>dateparser.parse("morgen") 5datetime.datetime(2020, 3, 15, 14, 39, 7, 314754)

Usingdateutil to Add Time Zones to Pythondatetime

One reason thatdateutil is so useful is that it includes an interface to the IANA time zone database. This takes the hassle out of assigning time zones to yourdatetime instances. Try out this example to see how to set adatetime instance to have your local time zone:

>>>fromdateutilimporttz>>>fromdatetimeimportdatetime>>>now=datetime.now(tz=tz.tzlocal())>>>nowdatetime.datetime(2020, 1, 26, 0, 55, 3, 372824, tzinfo=tzlocal())>>>now.tzname()'Eastern Standard Time'

In this example, youimporttz fromdateutil anddatetime fromdatetime. You then create adatetime instance set to the current time using.now().

You also pass thetz keyword to.now() and settz equal totz.tzlocal(). Indateutil,tz.tzlocal() returns a concrete instance ofdatetime.tzinfo. This means that it can represent all the necessary time zone offset and daylight saving time information thatdatetime needs.

You also print the name of the time zone using.tzname(), which prints'Eastern Standard Time'. This is the output for Windows, but on macOS or Linux, your output might read'EST' if you’re in the US Eastern time zone during the winter.

You can also create time zones that are not the same as the time zone reported by your computer. To do this, you’ll usetz.gettz() and pass the officialIANA name for the time zone you’re interested in. Here’s an example of how to usetz.gettz():

>>>fromdateutilimporttz>>>fromdatetimeimportdatetime>>>London_tz=tz.gettz("Europe/London")>>>now=datetime.now(tz=London_tz)>>>nowdatetime.datetime(2020, 1, 26, 6, 14, 53, 513460, tzinfo=tzfile('GB-Eire'))>>>now.tzname()'GMT'

In this example, you usetz.gettz() to retrieve the time zone information for London, United Kingdom and store it inLondon_tz. You then retrieve the current time, setting the time zone toLondon_tz.

On Windows, this gives thetzinfo attribute the valuetzfile('GB-Eire'). On macOS or Linux, thetzinfo attribute will look something liketzfile('/usr/share/zoneinfo/Europe/London), but it might be slightly different depending on wheredateutil pulls the time zone data from.

You also usetzname() to print the name of the time zone, which is now'GMT', meaning Greenwich Mean Time. This output is the same on Windows, macOS, and Linux.

In an earliersection, you learned that you shouldn’t use.utcnow() to create adatetime instance at the current UTC. Now you know how to usedateutil.tz to supply a time zone to thedatetime instance. Here’s an example modified from therecommendation in the Python documentation:

>>>fromdateutilimporttz>>>fromdatetimeimportdatetime>>>datetime.now(tz=tz.UTC)datetime.datetime(2020, 3, 14, 19, 1, 20, 228415, tzinfo=tzutc())

In this code, you usetz.UTC to set the time zone ofdatetime.now() to the UTC time zone. This method is recommended over usingutcnow() becauseutcnow() returns anaivedatetime instance, whereas the method demonstrated here returns anawaredatetime instance.

Next, you’ll take a small detour to learn aboutnaive vsawaredatetime instances. If you already know all about this, then you canskip ahead to improve your PyCon countdown with time zone information.

Comparing Naive and Aware Pythondatetime Instances

Pythondatetime instances support two types of operation, naive and aware. The basic difference between them is that naive instances don’t contain time zone information, whereas aware instances do. More formally, to quote the Python documentation:

An aware object represents a specific moment in time that is not open to interpretation. A naive object does not contain enough information to unambiguously locate itself relative to other date/time objects. (Source)

This is an important distinction for working with Pythondatetime. Anawaredatetime instance can compare itself unambiguously to other awaredatetime instances and will always return the correct time interval when used in arithmetic operations.

Naivedatetime instances, on the other hand, may be ambiguous. One example of this ambiguity relates to daylight saving time. Areas that practice daylight saving time turn the clocks forward one hour in the spring and backward one hour in the fall. This typically happens at 2:00 AM local time. In the spring, the hour from 2:00 AM to 2:59 AMnever happens, and in the fall, the hour from 1:00 AM to 1:59 AM happenstwice!

Practically, what happens is that the offset from UTC in these time zones changes throughout the year. IANA tracks these changes and catalogs them in the different database files that your computer has installed. Using a library likedateutil, which uses the IANA database under the hood, is a great way to make sure that your code properly handles arithmetic with time.

This doesn’t mean that you always need to use awaredatetime instances. But aware instances are crucial if you’re comparing times with each other, especially if you’re comparing times in different parts of the world.

Usingrelativedelta in Your PyCon Countdown

First, replace the plain subtraction operator withrelativedelta. With the subtraction operator, yourtimedelta object couldn’t count intervals of time larger than a day. However,relativedelta allows you to show the years, months, and days remaining:

 1# pyconcd.py 2 3fromdateutilimportparser,tz 4fromdateutil.relativedeltaimportrelativedelta 5fromdatetimeimportdatetime 6 7PYCON_DATE=parser.parse("May 12, 2021 8:00 AM") 8PYCON_DATE=PYCON_DATE.replace(tzinfo=tz.gettz("America/New_York")) 9now=datetime.now(tz=tz.tzlocal())1011countdown=relativedelta(PYCON_DATE,now)12print(f"Countdown to PyCon US 2021:{countdown}")

The only change that you made in this code was to replaceline 11 withcountdown = relativedelta(PYCON_DATE, now). The output from this script should tell you that PyCon US 2021 will happen in about one year and one month, depending on when you run the script.

However, that output isn’t very pretty since it looks like the signature ofrelativedelta(). You can build up some prettier output by replacingline 11 in the previous code with the code below:

11deftime_amount(time_unit:str,countdown:relativedelta)->str:12t=getattr(countdown,time_unit)13returnf"{t}{time_unit}"ift!=0else""1415countdown=relativedelta(PYCON_DATE,now)16time_units=["years","months","days","hours","minutes","seconds"]17output=(tfortuintime_unitsif(t:=time_amount(tu,countdown)))18print("Countdown to PyCon US 2021:",", ".join(output))

This code requires Python 3.8 because it uses the newwalrus operator. You can make this script work on older versions of Python by using a traditionalfor loop in place ofline 17.

In this code, you definetime_amount(), which takes two arguments, the unit of time and therelativedelta instance from which the time units should be retrieved. If the amount of time is not equal to zero, thentime_amount() returns a string with the amount of time and the time unit. Otherwise, it returns an empty string.

You usetime_amount() in thecomprehension online 17. That line creates agenerator storing the non-empty strings returned fromtime_amount(). It uses thewalrus operator to assign the return value oftime_amount() tot and includest only if it isTrue.

Finally,line 18 prints the final output using.join() on thegenerator. Next, you’ll take a look at including the PyCon date in the output from your script.

Showing the PyCon Date in Your PyCon Countdown

Earlier, you learned about creatingdatetime instances using.strptime(). This method uses a special mini-language within Python to specify how the date string is formatted.

Pythondatetime has an additional method called.strftime() that allows you to format adatetime instance to a string. In a sense, it’s the reverse operation of parsing using.strptime(). You can differentiate between the two methods by remembering that thep in.strptime() stands forparse, and thef in.strftime() stands forformat.

In your PyCon countdown, you can use.strftime() to print output to let the user know the date on which PyCon US will start. Remember, you can find the formatting codes that you want to use onstrftime.org. Now add this code online 18 of your PyCon countdown script:

18pycon_date_str=PYCON_DATE.strftime("%A, %B%d, %Y at %H:%M %p %Z")19print(f"PyCon US 2021 will start on:",pycon_date_str)20print("Countdown to PyCon US 2021:",", ".join(output))

In this code,line 18 uses.strftime() to create a string representing the starting date of PyCon US 2021. The output includes the weekday, month, day, year, hour, minute, AM or PM, and time zone:

Wednesday, May 12, 2021 at 08:00 AM EDT

Online 19, you print this string for the user to see with some explanatory text. The last line prints the amount of time remaining until the PyCon start date. Next, you’ll finish your script to make it easier for other people to reuse.

Finalizing Your PyCon Countdown

The final step that you’ll want take is to follow Pythonbest practices and put the code that produces output into amain() function. You can check out the full, final code after applying all these changes:

 1# pyconcd.py 2 3fromdateutilimportparser,tz 4fromdateutil.relativedeltaimportrelativedelta 5fromdatetimeimportdatetime 6 7PYCON_DATE=parser.parse("May 12, 2021 8:00 AM") 8PYCON_DATE=PYCON_DATE.replace(tzinfo=tz.gettz("America/New_York")) 910deftime_amount(time_unit:str,countdown:relativedelta)->str:11t=getattr(countdown,time_unit)12returnf"{t}{time_unit}"ift!=0else""1314defmain():15now=datetime.now(tz=tz.tzlocal())16countdown=relativedelta(PYCON_DATE,now)17time_units=["years","months","days","hours","minutes","seconds"]18output=(tfortuintime_unitsif(t:=time_amount(tu,countdown)))19pycon_date_str=PYCON_DATE.strftime("%A, %B%d, %Y at %H:%M %p %Z")20print(f"PyCon US 2021 will start on:",pycon_date_str)21print("Countdown to PyCon US 2021:",", ".join(output))2223if__name__=="__main__":24main()

In this code, you moveprint() and the code used for the generator intomain(). Online 23, you use theguard clause to make sure thatmain() only runs when this file is executed as ascript. This allows other people to import your code and reusePYCON_DATE, for instance, if they’d like.

Now you can modify this script as much as you want. One neat thing to do might be to allow the user to change the time zone associated withnow by passing acommand-line argument. You could also change thePYCON_DATE to something closer to home, sayPyCon Africa orEuroPython.

To get even more excited about PyCon, check outReal Python at PyCon US 2019 andHow to Get the Most Out of PyCon!